3RI - Sample Request and Response

On this page

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>

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/lookup

Production environment: https://gw.fraud.elavon.com/3ds2/lookup

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 the threeDSMethodData 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/authenticate

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

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 but 3D Secure 2.2 supports both messageCategory = 01 and 02.

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

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.

Related topics