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

Request query parameters

Field NameDescriptionRequiredLengthData Type
pageTokenA 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. 
OptionalNAString
limitMaximum 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. 
Optional1-50number

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 https://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 NameDescriptionLengthData Type
serviceProviderMerchantIdA unique ID of the merchant already registered on the integrator’s system.Min 1 char, max 35 chars String
tradeNameRegistered name of the merchant’s business.Min 1 char, max 200 charsString
businessWebsiteRegistered website address of the merchant’s business.
Must be a valid URL. Example: http://epicstore.com
Min 1 char, max 2048 charsString
countryCodeCountry code of the merchant’s registered business address. Example: USAValid ISO 3166-1 alpha-3 Country CodeString
merchantCategoryCodeMerchant category code indicates the type of good the merchant sells. Example: 00004 digitsString

Response parameters description

Field NameDescriptionLengthData Type
merchantIdA unique ID generated by Elavon to identify a merchant. A read-only field.Min 1 char, max 28 chars String
serviceProviderMerchantIdA unique ID of the merchant already registered on the integrator’s system.Min 1 char, max 35 chars String
tradeNameRegistered name of the merchant’s business.Min 1 char, max 200 charsString
businessWebsiteRegistered website address of the merchant’s business.
Must be a valid URL. Example: http://epicstore.com
Min 1 char, max 2048 charsString
countryCodeCountry code of the merchant’s registered business address. Example: USAValid ISO 3166-1 alpha-3 Country CodeString
merchantCategoryCodeMerchant category code indicates the type of good the merchant sells. Example: 00004 digitsString
statusIndicates 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
hrefLink 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=10Link opens new windowMin 1 char, max 2048 chars String
firstLink 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=10Link opens new windowMin 1 char, max 2048 chars String
nextLink 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=10Link opens new window

tip

You can use the field value as the request to retrieve the next page.

Min 1 char, max 2048 chars String
pageTokenA 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
nextPageTokenA 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
limitNumber of items to be returned per page. Default is 10 and maximum is 50.1 - 50 Number
sizeNumber 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
itemsArray that has service provider merchant objects. Each object will return the details associated with one merchant including its statusNA 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-aliasesLink opens new window

Basic Auth: integratorId:apiSecretKey

Sample Request

{
    "merchantId": "kwdwkg7grFVgxRWGfJFbG8Dt"    
}

Request parameters description

Field NameDescriptionRequiredLengthData Type
merchantIdA unique ID generated by Elavon to identify a merchant. A read-only field.RequiredMin 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 NameDescriptionLengthData Type
merchantAliasAn 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
integratorIdUnique ID of the integrator sending the request.28String
enabledStatus of the merchant alias.
Valid values:
  • true = merchant is enabled or active
  • false = merchant is disabled
NABoolean

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.

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