3RI: 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 /lookup
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/lookupopen_in_newLink opens new window
Production environment: https://gw.fraud.elavon.com/3ds2/lookupopen_in_newLink 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" : "7654310438700849",
"doBinLookup" : true,
"clientStartProtocolVersion": "2.1.0",
"clientEndProtocolVersion" : "2.2.0"
}
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"
}
note
The response returns the
acsInfoInd
field only for card schemes that support 3D Secure 2.2.0 for card ranges cache. At present, this field is returned only if the user is using a VISA, Mastercard, or Discover card.If you receive the
threeDSMethodURL
and thethreeDSMethodData
field values in the response, ignore these if the subsequent/authenticate
request is for a 3RI (merchant-initiated) transaction.
For additional /3ds2/lookup
scenarios, see Test scenarios - Sample /3ds2/lookup scenarios
To understand how the dsStartProtocolVersion
, dsEndProtocolVersion
, acsStartProtocolVersion
, and acsEndProtocolVersion
field values affect the next steps, review the /lookup response scenarios table in step 2 of the 3RI overview topic.
Authenticate request
Use the /authenticate
request to send a 3RI request authentication data to the 3DS server and receive an authentication response.
POST https://{host}/3ds2/authenticate
Sample URL
Test environment: https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticateopen_in_newLink opens new window
Production environment: https://gw.fraud.elavon.com/3ds2/authenticateopen_in_newLink opens new window
note
Use this sample request format only for authentication requests initiated by a merchant. If you are sending an authentication request for the first time for a cardholder, use either the or the Web SDK option.
3D Secure 2.1 supports only scenarios related to a non-payment transaction i.e. the
messageCategory
must always be02
but 3D Secure 2.2 supports bothmessageCategory
=01
and02
.The sample request and response on this page assume that the
acctNumber
supported 3DS 2 authentication and the issuer authenticated the transaction i.e.,transStatus
=Y
.
Sample request
{
"messageId": "Device_Channel_3",
"aReq": {
"messageVersion": "2.2.0",
"deviceChannel": "03",
"messageCategory": "02",
"threeRIInd": "04",
"acctNumber": "7654310438700849",
"acctType": "02",
"transType": "01",
"acctInfo": {
"chAccAgeInd": "05",
"chAccDate": "20170101",
"chAccChangeInd": "04",
"chAccChange": "20170101",
"chAccPwChangeInd": "05",
"chAccPwChange": "20170101",
"shipAddressUsageInd": "04",
"shipAddressUsage": "20170101",
"txnActivityDay": "1",
"txnActivityYear": "1",
"provisionAttemptsDay": "0",
"nbPurchaseAccount": "1",
"suspiciousAccActivity": "01",
"shipNameIndicator": "01",
"paymentAccInd": "05",
"paymentAccAge": "20170101"
},
"acctID": "personal account",
"merchantRiskIndicator": {
"shipIndicator": "01",
"deliveryTimeframe": "02",
"deliveryEmailAddress": "example@example.com",
"reorderItemsInd": "01",
"preOrderPurchaseInd": "02",
"preOrderDate": "20300101",
"giftCardAmount": "1",
"giftCardCurr": "840",
"giftCardCount": "01"
},
"cardExpiryDate": "2212",
"cardholderName": "Frictionless One",
"email": "example@example.com",
"billAddrLine1": "Billing Address Line 1",
"billAddrLine2": "Billing Address Line 2",
"billAddrLine3": "Billing Address Line 3",
"billAddrCity": "Atlanta",
"billAddrState": "GA",
"billAddrPostCode": "30303",
"billAddrCountry": "840",
"shipAddrLine1": "Shipping Address Line 1",
"shipAddrLine2": "Shipping Address Line 2",
"shipAddrLine3": "Shipping Address Line 3",
"shipAddrCity": "Athens",
"shipAddrState": "GA",
"shipAddrPostCode": "30603",
"shipAddrCountry": "840",
"mobilePhone": {
"cc": "123",
"subscriber": "123456789"
},
"homePhone": {
"cc": "123",
"subscriber": "123456789"
},
"workPhone": {
"cc": "123",
"subscriber": "123456789"
},
"threeDSRequestorPriorAuthenticationInfo": {
"threeDSReqPriorRef": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",
"threeDSReqPriorAuthMethod": "02",
"threeDSReqPriorAuthTimestamp": "201710282113",
"threeDSReqPriorAuthData": "cKTYtrvvKU7gUoiqbbO7Po"
}
},
"messageExtension": [
{
"name": "msgextname",
"id": "501341592B_0001_4567",
"criticalityIndicator": false,
"data": {
"valueOne": "messageextensiondata",
"valueTwo": "moremessageextensiondata"
}
}
],
"clientStartProtocolVersion": "2.2.0",
"clientEndProtocolVersion": "2.2.0"
}
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
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
messageType
messageVersion
- By default, the 3DS Server sets the value to2.1.0
. To use the 3DS 2.2 features, set to2.2.0
.threeDSServerTransID
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 merchant who does not process with Elavon (service provider merchant), 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
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.
Sample response
{
"messageId": "Device_Channel_3",
"aRes": {
"messageType": "ares",
"messageVersion": "2.2.0",
"threeDSServerTransID": "02316635-4588-424f-93de-65d0515300e4",
"dsTransID": "0f91325b-71a2-41d5-81e0-61110fbb2251",
"acsTransID": "da49dc91-2f94-4c4a-bcaa-9700b9d7b205",
"acsReferenceNumber": "3DS_LOA_ACS_PPFU_020100_00009",
"acsOperatorID": "ELAVON_ACS_EMULATOR_OPERATOR_ID1",
"dsReferenceNumber": "3DS_LOA_DIS_PPFU_020100_00010",
"transStatus": "Y",
"authenticationValue": "AABBCCDDEEFFAABBCCDDEEFFAAA=",
"eci": "00"
}
}
- 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.
To understand how the transStatus
field value affects the next steps, review the review the transStatus field value description table in step 3 of the 3RI overview topic.