Authentication - Sample Request and Response
Summary
Use this request to send the authentication data to the 3DS Server and receive the authentication response.
POST /3ds2/authenticate
Sample URL
- Test: https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticateopen_in_newLink opens new window
- Production: https://gw.fraud.elavon.com/3ds2/authenticateopen_in_newLink opens new window
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> |
note
The sample request and response on this page assume that the acctNumber
supports 3DS 2.1 authentication, but the issuer needs additional information from the cardholder to authenticate the transaction i.e. the response shows a challenge flow.
Sample request
{
"messageId" : "0b0deb70-3249-4c73-9cf5-92f6cac231af",
"aReq" : {
"addrMatch" : "Y",
"cardExpiryDate" : "1910",
"acctNumber" : "4100012356995210",
"billAddrLine1" : "Billing Address Line 1",
"billAddrLine2" : "Billing Address Line 2",
"billAddrLine3" : "Billing Address Line 3",
"billAddrPostCode" : "30303",
"billAddrCity" : "Atlanta",
"billAddrState" : "GA",
"billAddrCountry" : "840",
"email" : "cardholder@emaildomain.com",
"homePhone" : {
"cc" : "123",
"subscriber" : "123456789"
},
"mobilePhone" : {
"cc" : "123",
"subscriber" : "123456789"
},
"workPhone" : {
"cc" : "123",
"subscriber" : "123456789"
},
"cardholderName" : "Cardholder Name",
"shipAddrLine1" : "Shipping Address Line 1",
"shipAddrLine2" : "Shipping Address Line 2",
"shipAddrLine3" : "Shipping Address Line 3",
"shipAddrPostCode" : "30601",
"shipAddrCity" : "Athens",
"shipAddrState" : "GA",
"shipAddrCountry" : "840",
"deviceChannel" : "02",
"browserAcceptHeader" : "text/html,application/xhtml+xml,application/xml;q=0.9,\*/\*;q=0.8",
"browserIP" : "192.168.1.11",
"browserJavaEnabled" : true,
"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",
"messageCategory" : "01",
"purchaseAmount" : "1001",
"purchaseCurrency" : "978",
"purchaseExponent" : "2",
"purchaseDate" : "20170316141312",
"transType" : "01",
"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.1.0"
}
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 to2.1.0
. To force the 3DS Server to use the 3DS 1 authentication protocol, set it to1.0.2
.threeDSServerTransID
- If you are manually providing the value of thethreeDSServerTransID
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 service provider merchant (a merchant who does not process their payments with Elavon), 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
note
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 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 field description and valid values, see the API reference.
Sample response
{
"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="
}
- If the
transStatus
isY
orA
in the response, it will also returneci
andauthenticationValue
. - If the
transStatus
isN
,U
, orR
in the response, it will also return thetransStatusReason
field.
For additional /3ds2/authenticate
scenarios, see Test scenarios - Sample /3ds2/authenticate scenarios
Next step
- If the
notificationURL
was set to the 3DS Server, send a /challenge_result request to retrieve the challenge result. - If the
notificationURL
was set to merchant’s own server or a custom URL, send a /validate request to retrieve the challenge result data.