3D Secure 2 for merchants not processing with Elavon
On this page
Overview
Integrators can now choose Elavon to enable 3D Secure 2 capabilities in their payment services for all merchants, whether they are processing with Elavon or not. An integrator can be an MSP (merchant services provider), a PSP (payment service provider), or other partners who use the 3DS solution by Elavon and handle the payment relationship directly with the merchant. They can register the merchants that do not process with Elavon as a “service provider merchant” in Elavon’s 3DS Solution. Once a merchant is registered, the integrator can send a request to create a merchant alias for the service provider merchant. The integrator will use the merchant alias and their API key (the integrator’s API key) to retrieve the authentication token and send 3DS 2 related API requests on behalf of the merchant.
In summary, integrators can perform the following functions:
- create a service provider merchant
- update a service provider merchant by using its ID
- list a service provider merchant by using its ID
- list all associated service provider merchants
- delete a service provider merchant that is in an OPEN state
- create an alias for a service provider merchant that is in an OPEN state
important
The information on this page is only for merchants that are not processing with Elavon. Merchants who already process with Elavon and want to use the 3D Secure 2 solution should review the 3D Secure 2 integration options.
Merchant registration API
Once an integrator creates a service provider merchant, they can update, retrieve, and delete the service-provider-merchants.
Authentication
BasicAuth with integratorId as the user name and apiSecretKey as the password
Accept header: application/json UTF-8
Content-Type header: application/json
Create a service provider merchant
POST open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/service-provider-merchantsLink opens new window
Basic Auth base64 (integratorId:secretKey)
Sample request
{
"serviceProviderMerchantId": "12345678901234129",
"tradeName": "Epic Store",
"businessWebsite": "http://epicstore.com",
"countryCode": "USA",
"merchantCategoryCode": "6012"
}
Request parameters description
Sample response
If the request was valid, the response will return the generated merchantId and set the status to OPEN.
{
"merchantId": "w4drtvmq3wrq29k4rqjmwb4x46mw",
"serviceProviderMerchantId": "12345678901234129",
"tradeName": "Epic Store",
"businessWebsite": "http://epicstore.com",
"countryCode": "USA",
"merchantCategoryCode": "6012",
"status": "OPEN"
}
Response parameters description
important
Make a note of the merchantId returned in the response. You will need this ID to update, list, or delete a service provider merchant and to create a merchant alias. To retrieve the merchantId, you will need to send the list all request and then manually check all merchant objects to locate the merchantId of a specific service provider merchant.
Error scenarios
The response returns an error for the following conditions:
- HTTP Status code 400
- one or more parameters are missing or the request values do not conform to the requirements
- the integrator has already created a service provider merchant using the
serviceProviderMerchantId
- HTTP Status code 500
- internal server error
- service is unavailable
- database error
If you get the HTTP Status code 500, try to send the request after some time and if the error is persistent, contact Elavon support.
Update an existing service provider merchant resource
POST open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants/{merchantId}Link opens new window
note
The merchantId must have the same value that the Create a service provider merchant response returned.
Basic Auth base64 (integratorId:secretKey)
Sample request
{
"serviceProviderMerchantId": "12345678901234129",
"tradeName": "Epic Shop",
"businessWebsite": "http://epicshop.com",
"countryCode": "CAN",
"merchantCategoryCode": "6012"
}
note
The integrator can either send all or only those fields that they want to update.
Request parameters description
Sample response
A valid request will update the fields with the new field values. merchantId and status are read-only fields.
{
"merchantId": "vmkgxhfpmyfxmqx9d7dg8mp88gc6",
"serviceProviderMerchantId": "12345678901234129",
"tradeName": "Epic Shop",
"businessWebsite": "http://epicshop.com",
"countryCode": "CAN",
"merchantCategoryCode": "6012",
"status": "OPEN"
}
Response parameters description
Error scenarios
The response returns an error for the following conditions:
- HTTP Status code 400
- one or more parameters are missing or the values do not conform to the requirements
- HTTP Status code 403
- merchant status is
CLOSEDorFRAUD_CLOSED. An integrator cannot update a closed merchant. They can still use the GET Call to retrieve details of the closed merchant. To open a closed merchant, call Elavon support.
- merchant status is
- HTTP Status code 404
- merchant not found
- HTTP Status code 500
- internal server error
- service is unavailable
- database error
If you get the HTTP Status code 500, try to send the request after some time and if the error is persistent, contact Elavon support.
Get an existing service provider merchant resource
GET open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants/{merchantId}Link opens new window
note
The merchantId must have the same value that the Create a service provider merchant response returned.
Basic Auth base64 (integratorId:secretKey)
Sample response
{
"merchantId": "cvb68pkc2dgjk7wb4pqpyrfhhj79",
"serviceProviderMerchantId": "123456789012341292",
"tradeName": "Epic Store",
"businessWebsite": "http://epicstore.com",
"countryCode": "USA",
"merchantCategoryCode": "6012",
"status": "OPEN"
}
Response parameters description
Error scenarios
The response returns an error for the following conditions:
- HTTP Status code 404
- merchant not found
- HTTP Status code 500
- internal server error
- service is unavailable
- database error
If you get the HTTP Status code 500, try to send the request after some time and if the error is persistent, contact Elavon support.
List all existing service provider merchant resource
The API call to list all service provider merchant resources in Elavon’s database that belong to an integrator.
Basic Auth base64 (integratorId:secretKey)
GET open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?pageToken={}&limit={}Link opens new window
Request query parameters
| Field Name | Description | Required | Length | Data Type |
|---|---|---|---|---|
pageToken | A value that refers to the page number. If you are sending this request for the first time, do not specify this field in the query or pass a value of null. If not specified or set to null, the response returns only the list of merchants on the first page of the database. The response also returns the nextPageToken value. You can use this value as the pageToken in the subsequent request. | Optional | NA | String |
limit | Maximum number of service provider merchant details returned on a page. The returned list is sorted using the merchant’s tradeName in ascending order. The default value is 10. If you specify a value greater than 50, the response returns only 50 service provider merchants, if available. | Optional | 1-50 | number |
Sample response
The response returns the list of merchants that match the query parameters.
This sample response assumes the limit was set to 1 in the query parameter of the GET request.
{
"href": "https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?limit=1",
"first": "https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?limit=1",
"next": "https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?pageToken=MCwx&limit=1",
"pageToken": null,
"nextPageToken": "MCwx",
"limit": 1,
"size": 1,
"items": [
{
"merchantId": "69w3kvp6f33kq9vf98kjxk8trtbb",
"serviceProviderMerchantId": "12345678901234122",
"tradeName": "Epic Store",
"businessWebsite": "http://epicstore.com",
"countryCode": "USA",
"merchantCategoryCode": "1234",
"status": "OPEN"
}
]
}
note
If the integrator has not created any service provider merchant, the response returns an empty list. If the nextPageToken is null, it means that the current page is the last.
Response parameters description
Error scenarios
The response returns an error for the following conditions:
- HTTP Status code 500
- internal server erro
- service is unavailable
- database error
If you get the HTTP Status code 500, try to send the request after some time and if the error is persistent, contact Elavon support.
Delete an existing service provider merchant resource
The DELETE request changes the status of a merchant to CLOSE. It does not delete the merchant record from Elavon’s database. To open a closed merchant, call Elavon support.
DELETE open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants/{merchantId}Link opens new window
note
The merchantId must have the same value that the Create a service provider merchant response returned.
Basic Auth base64 (integratorId:secretKey)
Sample successful response
HTTP 204 - Successfully deletion
Error scenarios
The response returns an error for the following conditions:
- HTTP Status code 404
- merchant not found
- HTTP Status code 500
- internal server error
- service is unavailable
- database error
If you get the HTTP Status code 500, try to send the request after some time and if the error is persistent, contact Elavon support.
Request parameters description
note
All parameters are required in the Create a service provider merchant request, but optional in the Update a service provider merchant request.
| Field Name | Description | Length | Data Type |
|---|---|---|---|
serviceProviderMerchantId | A unique ID of the merchant already registered on the integrator’s system. | Min 1 char, max 35 chars | String |
tradeName | Registered name of the merchant’s business. | Min 1 char, max 200 chars | String |
businessWebsite | Registered website address of the merchant’s business. Must be a valid URL. Example: http://epicstore.com | Min 1 char, max 2048 chars | String |
countryCode | Country code of the merchant’s registered business address. Example: USA | Valid ISO 3166-1 alpha-3 Country Code | String |
merchantCategoryCode | Merchant category code indicates the type of good the merchant sells. Example: 0000 | 4 digits | String |
Response parameters description
| Field Name | Description | Length | Data Type |
|---|---|---|---|
merchantId | A unique ID generated by Elavon to identify a merchant. A read-only field. | Min 1 char, max 28 chars | String |
serviceProviderMerchantId | A unique ID of the merchant already registered on the integrator’s system. | Min 1 char, max 35 chars | String |
tradeName | Registered name of the merchant’s business. | Min 1 char, max 200 chars | String |
businessWebsite | Registered website address of the merchant’s business. Must be a valid URL. Example: http://epicstore.com | Min 1 char, max 2048 chars | String |
countryCode | Country code of the merchant’s registered business address. Example: USA | Valid ISO 3166-1 alpha-3 Country Code | String |
merchantCategoryCode | Merchant category code indicates the type of good the merchant sells. Example: 0000 | 4 digits | String |
status | Indicates the status of the merchant in Elavon’s database. A read-only field.Valid values:
| NA | String |
href | Link of the current page that lists the service provider merchants associated with the integrator. Example: open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?limit=10Link opens new window | Min 1 char, max 2048 chars | String |
first | Link of the first page that lists the service provider merchants associated with the integrator. Example: open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?limit=10Link opens new window | Min 1 char, max 2048 chars | String |
next | Link of the next page that lists the service provider merchants associated with the integrator. Example: open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?pageToken=MCwx&limit=10Link opens new window info_outline tip You can use the field value as the request to retrieve the next page. | Min 1 char, max 2048 chars | String |
pageToken | A base64-encoded value that refers to the page number. If you are sending this request for the first time, do not specify this field in the query or pass a value of null. If not specified or set to null, the response returns only the list of merchants on the first page of the database. | NA | String |
nextPageToken | A base64-encoded value that refers to the next page. You can use this value as the pageToken in the subsequent request. If the nextPageToken is null, it means that the current page is the last. | NA | String |
limit | Number of items to be returned per page. Default is 10 and maximum is 50. | 1 - 50 | Number |
size | Number of items returned per page. For example, if the limit is set to 10 but the integrator has only 8 service provider merchants, the size is returned as 8. If the limit is set to 10 but the integrator has 15 service provider merchants, the size is returned as 10. If you send a request to return the second page, the size is returned as 5. | 1 - 50 | Number |
items | Array that has service provider merchant objects. Each object will return the details associated with one merchant including its status. | NA | Array |
Merchant Alias API
Integrator can generate an alias for a merchant if the merchant meets the following conditions:
- is a service provider merchant
- is created by the integrator
- is in an OPEN state
The integrator will use the merchant alias and their API Key to retrieve the authentication token and send 3DS 2 related API requests on behalf of the merchant.
Create a merchant alias
POST open_in_newhttps://uat.integrator.converge.eu.elavonaws.com/merchant-aliasesLink opens new window
Basic Auth: integratorId:apiSecretKey
Sample Request
{
"merchantId": "kwdwkg7grFVgxRWGfJFbG8Dt"
}
Request parameters description
| Field Name | Description | Required | Length | Data Type |
|---|---|---|---|---|
merchantId | A unique ID generated by Elavon to identify a merchant. A read-only field. | Required | Min 1 char, max 28 chars | String |
Sample successful response
{
"merchantAlias": "cyrc3t9k2k2r8dydjy78t3tdfywf",
"integratorId": "2f7x346wwd4cd97y3v8yq9vj4yh6",
"enabled": true
}
note
Make a note of the merchantAlias returned in the response. You cannot retrieve this alias later. If you forget this alias, then you have to create a new alias.
Response parameters description
| Field Name | Description | Length | Data Type |
|---|---|---|---|
merchantAlias | An alias that is used in place of the merchantId in all API requests. The integrator uses the merchant alias and their API Key to retrieve the authentication token and send 3DS 2 related API requests on behalf of the merchant. | 28 | String |
integratorId | Unique ID of the integrator sending the request. | 28 | String |
enabled | Status of the merchant alias.Valid values:
| NA | Boolean |
Error scenarios
The response returns an error for the following conditions:
- HTTP Status code 400
merchantIdfield value is missingmerchantIdis not a valid Converge ID
- HTTP Status code 404
- merchant not found
- HTTP Status code 403
- merchant is closed or inactive
Next steps
After you have created a service provider merchant and an alias for the merchant, you can select the 3D Secure 2 integration options that work best in the merchant’s payment environment. Review the integration options and the sample use case scenarios to guide you.
note
When you send an /authenticate request for a service provider merchant, you must include the following fields. Otherwise, the 3DS Server returns an error.
- Acquirer Merchant Id (
acquirerMerchantID) - Acquirer BIN (
acquirerBIN) - 3DS Requestor ID (
threeDSRequestorID) - 3DS Requestor Name (
threeDSRequestorName)
If you are a merchant who is already processing with Elavon, you do not need to send these values. For such merchants, the 3DS Server appends these fields in the authenticate request that it sends to the ACS (Issuer). See the API Reference topic for the field descriptions.