Authentication - Sample Request and Response

Title: Send authentication data to the 3DS Server and get authentication response

 POST      /3ds2/authenticate

Sample URL

Test: https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

Production: https://https://gw.fraud.elavon.com/3ds2/authenticate

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>
error_outline

note

The sample request and response on this page assumes 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.

If the transStatus is Y or A in the response, it will also return eci and authenticationValue. If the transStatus is N, U, or R in the response, it will also return transStatusReason.

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"
}
error_outline

note

If you do not provide the value of following fields in the authentication data sent to the 3DS Server, the 3DS Server auto populates the value of these fields:

  • notificationURL 

By default, the 3DS Server receives the callbacks from the ACS. But if you want to opt out from the default challenge callback functionality and implement your own challenge response landing page, set the value of the notificationURL field in the /3ds2/authenticate request to a custom URL, where you can receive and monitor notifications. In such cases, you are responsible for handling notifications and continuing on with the 3DS flow. To fetch the challenge result data from the ACS, send the /3ds2/validate request instead of the /3ds2/challenge_result request.

  • threeDSServerTransID 

If you are manually providing the value of 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.

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

Related topics