Direct integration - Sample Request and Response

On this page

Headers

Lookup request

Use this 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

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

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

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

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 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 use the 3DS 2.2 features, set to 2.2.0.
• 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.

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 or A, the response also returns the eci and authenticationValue field values.

• For transStatus = N, U, or R, the response also returns the transStatusReason field value.

• For transStatus = I, the response returns the eci and authenticationValue 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 the notificationURL was sent to the 3DS Server, send a /challenge_result request to retrieve the challenge result.

• If you receive a transStatus = C and the notificationURL 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}

Sample URL

Test environment: https://uat.gw.fraud.eu.elavonaws.com/3ds2/challenge_result/102f8f6e-8472-4ada-8deb-91d5bd51de90open_in_newLink opens new window

Production environment: https://gw.fraud.elavon.com/3ds2/challenge_result/102f8f6e-8472-4ada-8deb-91d5bd51de90open_in_newLink opens new window

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: https://uat.gw.fraud.eu.elavonaws.com/3ds2/validateopen_in_newLink opens new window

Production environment: https://gw.fraud.elavon.com/3ds2/validateopen_in_newLink opens new window

Sample request

{
  "messageId": "c84a2370-ab74-4abe-97b7-2422a3b538b1",
  "cres": "ewogICJtZXNzYWdlVHlwZSI6ICJDUmVzIiwKICAibWVzc2FnZVZlcnNpb24iOiAiMi4xLjAiLAogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ICIwODg1Y2YzZS1hZjUxLTQ3NWMtYjI0Ni1mYjZjODRmMzI2ODEiLAogICJhY3NUcmFuc0lEIjogIjZmMmQ3YWY5LTlhNjYtNGUyYi04MjIwLTFlMDBiNmNmNzJkZSIsCiAgImNoYWxsZW5nZUNvbXBsZXRpb25JbmQiOiAiWSIsCiAgImFjc0NvdW50ZXJBdG9TIjogIjAwMSIsCiAgInRyYW5zU3RhdHVzIjogIkEiCn0="
}

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

Related topics

• Sample test scenarios

• API reference

• 3D Secure 2 for merchants not processing their payment with Elavon

• previousDirect integration to 3DS Server
• nextIntegrate using the Web SDK