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>

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
• threeDSRequestorID
• threeDSRequestorName
• acquirerBIN
• acquirerMerchantID
• 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 force the 3DS Server to use the 3DS 1 authentication protocol, set it to 1.0.2.
• 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.

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

Related topics

• Sample /3ds2/authenticate scenarios
• API reference

• previous Lookup - Sample Request and Response
• next Challenge Result - Sample Request and Response