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
error_outline

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

{   
    "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
error_outline

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

error_outline

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"                        
}
error_outline

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 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}

error_outline

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

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

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

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}

error_outline

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

error_outline

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:
  • OPEN - when the integrator creates a service provider merchant.
  • CLOSED -  when the integrator deletes a service provider merchant.
  • FRAUD_CLOSED - can be set only by Elavon.
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
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 https://uat.integrator.converge.eu.elavonaws.com/merchant-aliases

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                                           
}
error_outline

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:
  • true - merchant is enabled or active
  • false - merchant is disabled
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 integration options and the sample use case scenarios to guide you.

error_outline

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.

Related topics