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.

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

Cookie Settings

Elavon Financial Services DAC. Registered in Ireland – Number 418442.
Registered Office: Block F1, Cherrywood Business Park, Dublin 18, D18 W2X7, Ireland.
Elavon Financial Services DAC, trading as Elavon Merchant Services, is regulated by the Central Bank of Ireland.
 
Elavon Financial Services 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.
Elavon Financial Services 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.

## Headers

| Header name | Description | Required | Values |
| ----------- | ----------- | --------- | ------- |
| Content-Type | The MIME type of the request body. | Required | application/json |
| Authorization | Authorization type (Basic) and the base64 encoded username and password Or, Bearer followed by token | Required | Basic `<encoded_auth_data>` Or, Bearer `<token_value>` |

## Lookup request
Use this request to check the 3DS version and return version details.

` POST https://{host}/3ds2/lookup`

### Sample URL

**Test environment**: <https://uat.gw.fraud.eu.elavonaws.com/3ds2/lookup>

**Production environment**: <https://gw.fraud.elavon.com/3ds2/lookup>

:::::notice{note}

The sample `/lookup` request and response on this page assume that the `acctNumber` supports 3DS 2 authentication and additional information about the BIN is available.
:::::


### Sample request

```json
{
 "messageId" : "0b0deb70-3249-4c73-9cf5-92f6cac231af",
 "acctNumber" : "4017730000000005",
 "threeDSMethodNotificationURL" : "https://uat.gw.fraud.eu.elavonaws.com",
 "doBinLookup" : true,
 "clientStartProtocolVersion": "2.1.0",
 "clientEndProtocolVersion" : "2.2.0"
}
```

:::::notice{note}

The `threeDSMethodNotificationURL` receives the notification of 3DS Method completion from the ACS (issuer). The default value is the 3DS Server URL. To receive a notification on a custom URL, send the custom URL as the field value.
:::::


### Sample response

```json
{
 "messageId" : "0b0deb70-3249-4c73-9cf5-92f6cac231af",
 "threeDSServerTransID" : "102f8f6e-8472-4ada-8deb-91d5bd51de90",
 "dsStartProtocolVersion" : "2.1.0",
 "dsEndProtocolVersion" : "2.2.0",
 "acsStartProtocolVersion" : "2.1.0",
 "acsEndProtocolVersion" : "2.2.0",
 "directoryServerId" : "DirectoryServerID-DEMO-MC",
 "threeDSMethodURL" : "https://uat.acs.fraud.eu.elavonaws.com/acs/method/VISA",
 "threeDSMethodData" : "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cDovL2MyLWRldi1leHRlcm5hbC02NTY0ZDVlZDA2MjFjZjk0LmVsYi5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbToxMDg1MC9ub3RpZnkvbWV0aG9kX25vdGlmeSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMTAyZjhmNmUtODQ3Mi00YWRhLThkZWItOTFkNWJkNTFkZTkwIn0=",
 "acsInfoInd": ["01", "02", "03", "04"],
 "binInfo" :
 {
 "bin" : "401773",
 "scheme" : "Visa",
 "brand" : "Visa Electron",
 "fundingSource" : "prepaid",
 "issuingBank" : "GVS PREPAID LIMITED",
 "issuingCountry" : "IRL",
 "issuingCurrency" : "EUR",
 "isDebit" : "true",
 "isCorporate" : "false",
 "isDccAllowed" : "true"
 },
 "serverStartProtocolVersion": "2.1.0", 
 "serverEndProtocolVersion": "2.2.0"
}
```

For additional `/3ds2/lookup` scenarios, see :magic-link[Test scenarios - Sample /3ds2/lookup scenarios]{id="test-information"}

To understand how the `dsStartProtocolVersion`, `dsEndProtocolVersion`, `acsStartProtocolVersion`, and `acsEndProtocolVersion` field values in the response affect the next steps, review the :magic-link[/lookup response scenarios table ]{id="server-to-server-steps"} in step 3 of the Direct integration to 3DS Server topic.

## Authenticate request
Use this request to send authentication data to the 3DS Server and receive the authentication response.

`POST https://{host}/3ds2/authenticate`

### Sample URL

**Test environment**: <https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate>

**Production environment**: <https://gw.fraud.elavon.com/3ds2/authenticate>

:::::notice{note}

The sample `/authenticate` request and response on this page assume that the `acctNumber` supports 3DS 2 authentication, but the issuer needs additional information from the cardholder to authenticate the transaction i.e., the response returns the `transStatus = C`.
:::::


### Sample request

```json
{
 "messageId" : "0b0deb70-3249-4c73-9cf5-92f6cac231af",
 "aReq" : {
 "deviceChannel" : "02",
 "cardholderName" : "Cardholder Name",
 "acctNumber" : "4100012356995210",
 "cardExpiryDate" : "1910",
 "messageCategory" : "01",
 "purchaseAmount" : "1001",
 "purchaseCurrency" : "978",
 "purchaseExponent" : "2",
 "purchaseDate" : "20170316141312",
 "transType" : "01",
 "email" : "cardholder@emaildomain.com",
 "homePhone" : {
 "cc" : "123",
 "subscriber" : "123456789"
 },
 "mobilePhone" : {
 "cc" : "123",
 "subscriber" : "123456789"
 },
 "workPhone" : {
 "cc" : "123",
 "subscriber" : "123456789"
 },
 "billAddrLine1" : "Billing Address Line 1",
 "billAddrLine2" : "Billing Address Line 2",
 "billAddrLine3" : "Billing Address Line 3",
 "billAddrPostCode" : "30303",
 "billAddrCity" : "Atlanta",
 "billAddrState" : "GA",
 "billAddrCountry" : "840",
 "shipAddrLine1" : "Shipping Address Line 1",
 "shipAddrLine2" : "Shipping Address Line 2",
 "shipAddrLine3" : "Shipping Address Line 3",
 "shipAddrPostCode" : "30601",
 "shipAddrCity" : "Athens",
 "shipAddrState" : "GA",
 "shipAddrCountry" : "840",
 "addrMatch" : "Y",
 "browserAcceptHeader" : "text/html,application/xhtml+xml,application/xml;q=0.9,\*/\*;q=0.8",
 "browserIP" : "192.168.1.11",
 "browserJavaEnabled" : true,
 "browserJavascriptEnabled" : true, //Required only for 3DS 2.2
 "browserLanguage" : "en",
 "browserColorDepth" : "48",
 "browserScreenHeight" : "400",
 "browserScreenWidth" : "600",
 "browserTZ" : "-240",
 "browserUserAgent" : "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0",
 "threeDSRequestorAuthenticationInd" : "01",
 "threeDSRequestorAuthenticationInfo" : {
 "threeDSReqAuthMethod" : "02",
 "threeDSReqAuthTimestamp" : "201711071307",
 "threeDSReqAuthData" : "cKTYtrvvKU7gUoiqbbO7Po"
 },
 "threeDSRequestorChallengeInd" : "02",
 "threeDSRequestorPriorAuthenticationInfo" : {
 "threeDSReqPriorRef" : "d7c1ee99-9478-44a6-b1f2-391e29c6b340",
 "threeDSReqPriorAuthMethod" : "02",
 "threeDSReqPriorAuthTimestamp" : "201710282113",
 "threeDSReqPriorAuthData" : "cKTYtrvvKU7gUoiqbbO7Po"
 },
 "acctType" : "03",
 "acctInfo" : {
 "chAccAgeInd" : "03",
 "chAccDate" : "20140328",
 "chAccChangeInd" : "04",
 "chAccChange" : "20160712",
 "chAccPwChangeInd" : "02",
 "chAccPwChange" : "20170328",
 "shipAddressUsageInd" : "04",
 "shipAddressUsage" : "20160714",
 "txnActivityDay" : "01",
 "txnActivityYear" : "21",
 "provisionAttemptsDay" : "0",
 "nbPurchaseAccount" : "11",
 "suspiciousAccActivity" : "01",
 "shipNameIndicator" : "02",
 "paymentAccInd" : "04",
 "paymentAccAge" : "20160917"
 },
 "acctID" : "personal account",
 "purchaseInstalData" : "24",
 "merchantRiskIndicator" : {
 "shipIndicator" : "02",
 "deliveryTimeframe" : "01",
 "deliveryEmailAddress" : "deliver@email.com",
 "reorderItemsInd" : "01",
 "preOrderPurchaseInd" : "02",
 "preOrderDate" : "20170519",
 "giftCardAmount" : "337",
 "giftCardCurr" : "840",
 "giftCardCount" : "02"
 },
 "messageExtension" : [
 {
 "name" : "msgextname",
 "id" : "501341592B_0001_4567",
 "criticalityIndicator" : false,
 "data" : {
 "valueOne": "messageextensiondata",
 "valueTwo": "moremessageextensiondata",
 }
 }
 ],
 "recurringExpiry" : "20180131",
 "recurringFrequency" : "06",
 "broadInfo" : {
 "message" : "TLS 1.x will be turned off starting summer 2019"
 }
 },
 "challengeParameters" : {
 "challengeWindowSize" : "04"
 },
 "clientStartProtocolVersion": "2.1.0",
 "clientEndProtocolVersion": "2.2.0"
}
```

:::::notice{note}

- To send the data only for information purposes and no authentication required (i.e., to receive `transStatus = I` in the response), you must send a value of either `05, 06, or 07` in the `threeDSRequestorChallengeInd` field.

- Merchants who operate in the travel industry can send additional travel-related data in the `messageExtension` object of the `/authenticate` request. For a sample of the `messageExtension` object and field details, see message extension elements for the travel industry

- To understand more about the 3DS Server fallback strategy, review the 3DS Server fallback strategy table in step 4 of the Direct integration to 3DS Server topic.
:::::


To increase the chances of successful authentication, include information for all required and optional fields in the authentication request you send to the 3DS Server. However, do not send dummy data if you do not have data for an optional field. For description and valid values for these fields, see the :magic-link[API reference]{id="api-reference"}.

**Fields auto-populated by the 3DS Server in the `/authenticate` request**

The 3DS Server auto-populates and appends the following fields in the authentication request it sends to the ACS (issuer) in addition to the data you send:

- `merchantName`
- `merchantCountryCode`
- `mcc`
- `threeDSRequestorURL`
- `threeDSServerURL`
- `threeDSServerOperatorID`
- `threeDSServerRefNumber`
- `threeDSCompInd`
- `messageType`
- `notificationURL` - By default, the 3DS Server receives the callbacks from the ACS. But if you want to opt-out from the default challenge callback capability and implement your own challenge-response landing page, set the value of this field to a custom URL, where you can receive and monitor notifications. In such cases, you are responsible for handling notifications and continuing with the 3DS flow. In case the authentication response returns the `transStatus` = `C`, then to fetch the challenge result data from the ACS, send the `/3ds2/validate request` instead of the `/3ds2/challenge_result request`.
- `messageVersion` - By default, the 3DS Server sets the value to `2.1.0`. To use the 3DS 2.2 features, set to `2.2.0`.
- `threeDSServerTransID` - If you are manually providing the value of the `threeDSServerTransID` field in the`/3ds2/authenticate` request, you must use the same value you received in the corresponding `/3ds2/lookup response`. If you did not make a `/3ds2/lookup` request, do not include this field in the `/3ds2/authenticate` request.

The 3DS Server auto-populates and appends the following fields in the aReq request body only for merchants who process their payment with Elavon. For a :magic-link[service provider merchant who does not process their payments with Elavon]{id="service-provider"}, you must send the following field values in the aReq request body. The 3DS Server returns an error if any of these field values are missing in the request.

- `threeDSRequestorID`
- `threeDSRequestorName`
- `acquirerBIN`
- `acquirerMerchantID`


### Sample response

```json
{
 "messageId" : "0b0deb70-3249-4c73-9cf5-92f6cac231af",
 "aRes" : {
 "messageType" : "ARes",
 "messageVersion" : "2.1.0",
 "threeDSServerTransID" : "102f8f6e-8472-4ada-8deb-91d5bd51de90",
 "dsTransID" : "d9efdb88-2277-408b-859a-a16ec843395b",
 "acsTransID" : "7a3378fe-cea0-4762-8035-c0b91d7e7d0e",
 "acsReferenceNumber" : "ELAVON_ACS_EMULATOR_REF_NUMBER32",
 "acsOperatorID" : "ELAVON_ACS_EMULATOR_OPERATOR_ID1",
 "dsReferenceNumber" : "ELAVON_3DS_DS_EMULATOR_REF_NUM32",
 "transStatus" : "C",
 "authenticationType" : "01",
 "acsChallengeMandated" : "Y",
 "acsURL" : "https://uat.acs.fraud.eu.elavonaws.com/acs/challenge/VISA"
 },
 "creq" :
"eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxMDJmOGY2ZS04NDcyLTRhZGEtOGRlYi05MWQ1YmQ1MWRlOTAiLCJhY3NUcmFuc0lEIjoiN2EzMzc4ZmUtY2VhMC00NzYyLTgwMzUtYzBiOTFkN2U3ZDBlIn0="
}
```
- For `transStatus` = `Y` or `A`, the response also returns the `eci` and `authenticationValue` field values.
- For `transStatus` = `N`, `U`, or `R`, the response also returns the `transStatusReason` field value.

- For `transStatus` = `I`, the response returns the `eci` and `authenticationValue` field values based on the directory server (DS) rules.

For additional `/3ds2/authenticate` scenarios, see :magic-link[Test scenarios - Sample /3ds2/authenticate scenarios]{id="test-information"}

After you receive the `/authenticate` response, choose one of the following actions based on the response you receive:

- If you receive a `transStatus = C` and the `notificationURL` was sent to the 3DS Server, send a `/challenge_result request` to retrieve the challenge result.

- If you receive a `transStatus = C` and the `notificationURL` was sent to the merchant's server or a custom URL, send a `/validate request` to retrieve the challenge result data.

To understand how the `transStatus` field value affects the next steps, review the :magic-link[transStatus field value description table]{id="server-to-server-steps"} in step 5 of the Direct integration to 3DS Server topic.

## Challenge result request
Use this request to retrieve the challenge result of the specified `threeDSServerTransID`.

`GET https://{host}/3ds2/challenge_result/{threeDSServerTransID}`

:::::notice{important}

You must use the `threeDSServerTransID` value you received in the `/3ds2/authenticate response` request. 
:::::

 
### Sample URL

**Test environment**: <https://uat.gw.fraud.eu.elavonaws.com/3ds2/challenge_result/102f8f6e-8472-4ada-8deb-91d5bd51de90>

**Production environment**: <https://gw.fraud.elavon.com/3ds2/challenge_result/102f8f6e-8472-4ada-8deb-91d5bd51de90>

:::::notice{note}

- For `transStatus = C`, send a `/challenge_result request` request only if the `notificationURL` was sent to the 3DS Server. If the `notificationURL` was sent to merchant's server or a custom URL, send a `/validate request` request instead.

- The sample request and response on this page assume that the `acctNumber` supported 3DS 2 authentication, but the issuer needed additional information from the cardholder to authenticate the transaction i.e., a challenge flow. After the cardholder provided additional information to the issuer, it authenticates the transaction i.e., `transStatus = Y`.
:::::


### Sample response

```json
{
 "messageType" : "RReq",
 "messageVersion" : "2.2.0",
 "threeDSServerTransID" : "102f8f6e-8472-4ada-8deb-91d5bd51de90",
 "dsTransID" : "d9efdb88-2277-408b-859a-a16ec843395b",
 "acsTransID" : "7a3378fe-cea0-4762-8035-c0b91d7e7d0e",
 "authenticationType" : "01",
 "authenticationValue" : "CQXYpVZrNni678cpEUQK0DZRTfQ=",
 "eci" : "05",
 "interactionCounter" : "01",
 "messageCategory" : "01",
 "transStatus" : "Y"
}
```
## Validate request
Use this request to send the `cres` to Elavon to retrieve the challenge result. 

`POST https://{host}/3ds2/validate`
 
### Sample URL

**Test environment**: <https://uat.gw.fraud.eu.elavonaws.com/3ds2/validate>

**Production environment**: <https://gw.fraud.elavon.com/3ds2/validate>

:::::notice{note}

- For `transStatus = C`, send a `/validate request` request to retrieve the challenge result only if the `notificationURL` was sent to merchant's server or a custom URL. If the `notificationURL` was sent to the 3DS Server, send a `/challenge_result request` request instead.

- The sample request and response on this page assume that the `acctNumber` supported 3DS 2 authentication, but the issuer needed additional information from the cardholder to authenticate the transaction i.e., a challenge flow. After the cardholder provided additional information to the issuer, it authenticates the transaction i.e., `transStatus = Y`.
:::::


### Sample request

``` json
{
 "messageId": "c84a2370-ab74-4abe-97b7-2422a3b538b1",
 "cres": "ewogICJtZXNzYWdlVHlwZSI6ICJDUmVzIiwKICAibWVzc2FnZVZlcnNpb24iOiAiMi4xLjAiLAogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ICIwODg1Y2YzZS1hZjUxLTQ3NWMtYjI0Ni1mYjZjODRmMzI2ODEiLAogICJhY3NUcmFuc0lEIjogIjZmMmQ3YWY5LTlhNjYtNGUyYi04MjIwLTFlMDBiNmNmNzJkZSIsCiAgImNoYWxsZW5nZUNvbXBsZXRpb25JbmQiOiAiWSIsCiAgImFjc0NvdW50ZXJBdG9TIjogIjAwMSIsCiAgInRyYW5zU3RhdHVzIjogIkEiCn0="
}
```

:::::notice{important}

You must use the `messageId` and the base64-encoded `cres` values you received from the ACS.
:::::


### Sample response

```json
{
 "messageId": "c84a2370-ab74-4abe-97b7-2422a3b538b1",
 "threeDSServerTransID": "0885cf3e-af51-475c-b246-fb6c84f32681",
 "valid": true,
 "rReq":{
 "messageType": "RReq",
 "messageVersion": "2.2.0",
 "threeDSServerTransID": "0885cf3e-af51-475c-b246-fb6c84f32681",
 "dsTransID": "adb4e259-8e30-4c7e-8cb7-87fd44a22075",
 "acsTransID": "6f2d7af9-9a66-4e2b-8220-1e00b6cf72de",
 "authenticationType": "01",
 "authenticationValue": "lIZK0RcpcDZ83vutqkwrZqJ0fl4=",
 "eci": "06",
 "interactionCounter": "01",
 "messageCategory": "01",
 "transStatus": "Y"
 }
}
```

Direct integration - Sample Request and Response