Direct integration - Sample Request and Response
On this page
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: open_in_newhttps://uat.gw.fraud.eu.elavonaws.com/3ds2/lookupLink opens new window
Production environment: open_in_newhttps://gw.fraud.elavon.com/3ds2/lookupLink opens new window
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
{
"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"
}
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
{
"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 Test scenarios - Sample /3ds2/lookup scenarios
To understand how the dsStartProtocolVersion
, dsEndProtocolVersion
, acsStartProtocolVersion
, and acsEndProtocolVersion
field values in the response affect the next steps, review the /lookup response scenarios table 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: open_in_newhttps://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticateLink opens new window
Production environment: open_in_newhttps://gw.fraud.elavon.com/3ds2/authenticateLink opens new window
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
{
"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"
}
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 either05, 06, or 07
in thethreeDSRequestorChallengeInd
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 themessageExtension
object and field details, see message extension elements for the travel industryTo 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 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 thetransStatus
=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 use the 3DS 2.2 features, set to2.2.0
.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
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="
}
For
transStatus
=Y
orA
, the response also returns theeci
andauthenticationValue
field values.For
transStatus
=N
,U
, orR
, the response also returns thetransStatusReason
field value.For
transStatus
=I
, the response returns theeci
andauthenticationValue
field values based on the directory server (DS) rules.
For additional /3ds2/authenticate
scenarios, see Test scenarios - Sample /3ds2/authenticate scenarios
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 thenotificationURL
was sent to the 3DS Server, send a/challenge_result request
to retrieve the challenge result.If you receive a
transStatus = C
and thenotificationURL
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 transStatus field value description table 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}
important
You must use the threeDSServerTransID
value you received in the /3ds2/authenticate response
request.
Sample URL
Test environment: open_in_newhttps://uat.gw.fraud.eu.elavonaws.com/3ds2/challenge_result/102f8f6e-8472-4ada-8deb-91d5bd51de90Link opens new window
Production environment: open_in_newhttps://gw.fraud.elavon.com/3ds2/challenge_result/102f8f6e-8472-4ada-8deb-91d5bd51de90Link opens new window
note
For
transStatus = C
, send a/challenge_result request
request only if thenotificationURL
was sent to the 3DS Server. If thenotificationURL
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
{
"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: open_in_newhttps://uat.gw.fraud.eu.elavonaws.com/3ds2/validateLink opens new window
Production environment: open_in_newhttps://gw.fraud.elavon.com/3ds2/validateLink opens new window
note
For
transStatus = C
, send a/validate request
request to retrieve the challenge result only if thenotificationURL
was sent to merchant’s server or a custom URL. If thenotificationURL
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
{
"messageId": "c84a2370-ab74-4abe-97b7-2422a3b538b1",
"cres": "ewogICJtZXNzYWdlVHlwZSI6ICJDUmVzIiwKICAibWVzc2FnZVZlcnNpb24iOiAiMi4xLjAiLAogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ICIwODg1Y2YzZS1hZjUxLTQ3NWMtYjI0Ni1mYjZjODRmMzI2ODEiLAogICJhY3NUcmFuc0lEIjogIjZmMmQ3YWY5LTlhNjYtNGUyYi04MjIwLTFlMDBiNmNmNzJkZSIsCiAgImNoYWxsZW5nZUNvbXBsZXRpb25JbmQiOiAiWSIsCiAgImFjc0NvdW50ZXJBdG9TIjogIjAwMSIsCiAgInRyYW5zU3RhdHVzIjogIkEiCn0="
}
important
You must use the messageId
and the base64-encoded cres
values you received from the ACS.
Sample response
{
"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"
}
}