Elavon downloads and stores cookies on your device when you visit our website. We use these cookies to better understand and improve your browsing experience by identifying most visited pages, personalising content, and measuring site performance.

Essential cookies enable core functionality such as page navigation and access to secure areas. The website cannot function properly without these cookies; they can only be disabled by changing your browser preferences.

These are cookies that support site functionality that is visible or advantageous to you or your experience of the site, they enable websites to remember choices and provide a more personalized experience.   Functional cookies help to provide services that you request, such as language preference or layout.

Performance cookies help us to improve our website by collecting and reporting information on its usage (for example, which of our pages are most frequently visited).

These cookies and similar technologies gather information about your browsing habits. They remember that you've visited a website and share this information with other organisations, such as advertisers and platforms on which we advertise. They do this in order to provide you with ads that are more relevant to you and your interests. Although these cookies and similar technologies can track your visits to other websites, they don't usually know who you are. Without these cookies, online advertisements you encounter will be less relevant to you and your interests.

Cookie Settings

U.S. Bank Europe DAC. Registered in Ireland – Number 418442..  Registered Office: Block F1, Cherrywood Business Park, Dublin 18, D18 W2X7, Ireland.
U.S. Bank Europe DAC, trading as Elavon Merchant Services, is regulated by the Central Bank of Ireland.
 
U.S. Bank Europe DAC. Registered in Ireland with Companies Registration Office. The liability of the member is limited. United Kingdom branch registered in England and Wales under the number BR022122.
U.S. Bank Europe DAC, trading as Elavon Merchant Services, is a credit institution authorised and regulated by the Central Bank of Ireland.  Authorised by the Prudential Regulation Authority.  Subject to regulation by the Financial Conduct Authority and limited regulation by the Prudential Regulation Authority.  Details about the extent of our regulation by the Prudential Regulation Authority are available from us on request.

Most popular solutions

Additional solutions

Fusebox integration & options

Optional platform features

Documentation

North America

Europe

Regions

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

:::::notice{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 <https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants>

`Basic Auth base64 (integratorId:secretKey)`

#### Sample request

``` json
{ 
 "serviceProviderMerchantId": "12345678901234129", 
 "tradeName": "Epic Store", 
 "businessWebsite": "http://epicstore.com", 
 "countryCode": "USA", 
 "merchantCategoryCode": "6012" 
}
```

#### Sample response
If the request was valid, the response will return the generated `merchantId` and set the status to `OPEN`.

``` json
{
 "merchantId": "w4drtvmq3wrq29k4rqjmwb4x46mw", 
 "serviceProviderMerchantId": "12345678901234129",
 "tradeName": "Epic Store",
 "businessWebsite": "http://epicstore.com",
 "countryCode": "USA",
 "merchantCategoryCode": "6012",
 "status": "OPEN" 
}
```

**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-existing-service-provider-merchant-resource 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 <https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants/{merchantId}>

:::::notice{note}

The `merchantId` must have the same value that the Create a service provider merchant response returned.
:::::


`Basic Auth base64 (integratorId:secretKey)`

#### Sample request
``` json
{ 
 "serviceProviderMerchantId": "12345678901234129",
 "tradeName": "Epic Shop", 
 "businessWebsite": "http://epicshop.com",
 "countryCode": "CAN", 
 "merchantCategoryCode": "6012" 
}
```

:::::notice{note}

The integrator can either send all or only those fields that they want to update. 
:::::


#### Sample response
A valid request will update the fields with the new field values. `merchantId` and `status` are read-only fields.

``` json
{
 "merchantId": "vmkgxhfpmyfxmqx9d7dg8mp88gc6",
 "serviceProviderMerchantId": "12345678901234129",
 "tradeName": "Epic Shop",
 "businessWebsite": "http://epicshop.com",
 "countryCode": "CAN",
 "merchantCategoryCode": "6012",
 "status": "OPEN"
}
```

#### 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 `CLOSED` or `FRAUD_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. 
- 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 <https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants/{merchantId}>

:::::notice{note}

The `merchantId` must have the same value that the Create a service provider merchant response returned.
:::::


`Basic Auth base64 (integratorId:secretKey)`

#### Sample response
``` json
{
 "merchantId": "cvb68pkc2dgjk7wb4pqpyrfhhj79",
 "serviceProviderMerchantId": "123456789012341292",
 "tradeName": "Epic Store",
 "businessWebsite": "http://epicstore.com",
 "countryCode": "USA",
 "merchantCategoryCode": "6012",
 "status": "OPEN" 
}
```

#### 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 <https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?pageToken={}&limit={}>

#### 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.

``` json
{
 "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"
 }
 ] 
}
```

:::::notice{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.
:::::

#### 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 <https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants/{merchantId}>

:::::notice{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

:::::notice{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:** <ul><li>OPEN = when the integrator creates a service provider merchant.</li><li>CLOSED = when the integrator deletes a service provider merchant.</li><li>FRAUD_CLOSED = can be set only by Elavon.</li></ul> | NA | String |
| `href` | Link of the current page that lists the service provider merchants associated with the integrator. Example: <https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?limit=10> | Min 1 char, max 2048 chars | String |
| `first` | Link of the first page that lists the service provider merchants associated with the integrator. Example: <https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?limit=10> | Min 1 char, max 2048 chars | String |
| `next` | Link of the next page that lists the service provider merchants associated with the integrator. Example: <https://uat.integrator.converge.eu.elavonaws.com/service-provider-merchants?pageToken=MCwx&limit=10> 
 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 <https://uat.integrator.converge.eu.elavonaws.com/merchant-aliases>

`Basic Auth: integratorId:apiSecretKey`

#### Sample Request
``` json
{
 "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
``` json
{
 "merchantAlias": "cyrc3t9k2k2r8dydjy78t3tdfywf",
 "integratorId": "2f7x346wwd4cd97y3v8yq9vj4yh6", 
 "enabled": true 
}
```

:::::notice{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:** <ul><li>true = merchant is enabled or active</li><li>false = merchant is disabled</li></ul> | NA | Boolean |

#### Error scenarios
The response returns an error for the following conditions:

- HTTP Status code 400 
 - `merchantId` field value is missing
 - `merchantId` is 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 :magic-link[integration options and the sample use case scenarios ]{id="integration-options"} to guide you.

:::::notice{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).

:::::

3DS 2 for merchants not processing with Elavon