3RI Authentication - Sample Request and Response

Title: Send a 3RI request authentication data to the 3DS server and get authentication response

 POST     /3ds2/authenticate  

Sample URL

Headers

Header nameDescriptionRequiredValues
Content-TypeThe MIME type of the request body.Requiredapplication/json
AuthorizationAuthorization type (Basic) and the base64 encoded username and password
Or
Bearer followed by token
RequiredBasic <encoded_auth_data>
Or
Bearer <token_value>

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 direct integration or the Web SDK option.

  • 3D Secure 2.1 supports only scenarios related to a non-payment transaction i.e. the messageCategory must always be 02.

  • The sample request and response on this page assume that the acctNumber supported 3DS 2.1 authentication and the issuer authenticated the transaction i.e., transStatus = Y.

Sample authentication request 

{
  "messageId": "Device_Channel_3",
  "aReq": {
     "messageVersion" : "2.1.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

  • Do not set the value of clientStartProtocolVersion field to 1.0.2 to enable 3DS 1 fallback. The 3DS Server will return an error message. It is not a supported scenario for 3RI transactions i.e., deviceChannel = 03.

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

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 field description and valid values, see the API reference.

Sample authentication response

{
    "messageId" : "Device_Channel_3",
    "aRes" : {
      "messageType" : "ares",
      "messageVersion" : "2.1.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 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.

Use the test card numbers to simulate different transaction status flow.

Related topics