3DS 1 Fallback

If you are an integrator who only supports 3D Secure 1 (3DS 1), or if the Issuer does not support 3D Secure 2 (3DS 2), you can still implement Elavon's Fraud Services solution. Transactions that need 3DS 1 authentication are appropriately redirected to the 3DS 1 authentication flow. The flowchart below shows how the following fields in the authenticate request help the 3DS Server decide whether to follow 3DS 2 or 3DS 1 authentication flow: messageVersion, clientStartProtocolVersion, and clientEndProtocolVersion

Figure caption: Decision matrix used by 3DS Server to initiate 3DS 1 fallback

High-level steps for integration with Elavon’s 3DS Server with fallback support

1. Complete the setup prerequisites
2. Prepare your website’s payment page for 3DS authentication
3. Collect cardholder data
4. (Optional) Send cardholder’s card (acctNumber) to verify support for 3DS 1 or 3DS 2 (/3ds2/lookup)
5. Send additional cardholder data for transaction authentication (/3ds2/authenticate)
6. Send details to ACS for challenge completion and receive PaRes from the ACS
7. Validate authenticate response (PaRes) with the 3DS Server (/3ds2/validate)

Step 1: Complete the setup prerequisites

• To receive authentication credentials that you would need to test the different integration options in the sandbox environment, fill in the information requested in this form.

  3D Secure 2 test credentials request form open_in_new Open link in new window

  error_outline

  important

  Never expose your API key in the client-side code.

  For more details on authentication mechanisms supported by Elavon for 3D Secure, see Authentication.

• Set up a test and a production environment.

(Optional) Step 2: Prepare your website’s payment page for 3D Secure authentication

Perform this step if you are integrating directly with the 3DS Server and you want to implement a custom challenge-response receiver page. In that case, specify a custom URL in the notificationURL field in the /3ds2/authenticate request. Any notifications from the ACS will be redirected to this page, for example, the notification of the Payer Authentication Response (PaRes). You must pass this URL as the TermUrl when you redirect the customer to the ACS (acsURL) for 3DS 1 authentication (see Step 6).

Before you begin 3D Secure authentication for a transaction, you must register an event listener code on your payment page. Perform this step only once; it is unnecessary to repeat it for every transaction.

Sample code to handle the PaRes receiver

/**
 * Example code for PaRes receiver
 */

@RequestMapping(
    path = "handle_3DS1_pares", 
    method = RequestMethod.POST,
    consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE,
    produces = MediaType.TEXT_HTML_VALUE)
@ResponseStatus(HttpStatus.OK)
@ApiOperation(value = "Receive PaRes and MD from ACS and call Elavon 3DS Server validate")
@ApiResponses(value = @ApiResponse(code = 200, message = "Successful Request"))
public ResponseEntity<RReq>(
    @RequestParam String PaRes,
    @RequestParam String MD)
    throws Exception
{   try
    {           
     //create 3DS Server /validate Request
     ThreeDSValidateRequest request = ThreeDSValidateRequest.builder()
        .messageId("sample_messageId")
        .PaRes(PaRes)
        .MD(MD)
        .build();
     //call 3DS Server validate call and POST request to /validate path with your client implementation
     ThreeDSValidateResponse response = threeDSServerClient.validate(request);
       //check if PaRes passed validation
       if (response.getValid())
        {
          return ResponseEntity.ok(response.getRReq());
        }
        else
        {
          //handle PaRes failed validation
        }
    }
    catch (Exception ex)
    {           
      //handle any exceptions
    } 
}

Step 3: Collect cardholder data

To initiate a payment request for the cardholder’s purchase, collect the cardholder data entered on the merchant’s website.

Step 4: (Optional) Send cardholder’s acctNumber to verify support for 3DS 1 or 3DS 2 (/3ds2/lookup)

Use the POST /3ds2/lookup call to send the acctNumber to the 3DS Server. The 3DS Server first verifies if the issuer of the card supports 3DS 2. If 3DS 2 is not supported, the server checks if 3DS 1 fallback is enabled (i.e. clientStartProtocolVersion = 1.0.2) and whether the acctNumber supports 3DS 1. When the server performs this check, the following scenarios are possible.

Sample URL

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

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

Scenario 1: Client supports only 3DS 1

When the client supports only 3DS1, set the values of both clientStartProtocolVersion and clientEndProtocolVersion fields to 1.0.2 in the /3ds2/lookup request. The 3DS Server checks if the acctNumber supports 3DS 1, and if supported, it returns the following /3ds2/lookup response:

Example request

{
  "messageId": "sample-test",
  "acctNumber": "40XXXXXXXXXX0005",
  "doBinLookup" : false,
  "clientStartProtocolVersion": "1.0.2",
  "clientEndProtocolVersion" : "1.0.2"
}

Example response

{
  "messageId": "sample-test",
  "threeDSServerTransID": "67b76006-c6a6-4956-915b-0df41fc47b83",
  "dsStartProtocolVersion": "1.0.2",
  "dsEndProtocolVersion": "1.0.2",
  "acsStartProtocolVersion": "1.0.2",
  "acsEndProtocolVersion": "1.0.2",
  "serverStartProtocolVersion": "1.0.2",
  "serverEndProtocolVersion": "2.1.0"
}

See Step 5 - Send additional cardholder data for transaction authentication (/3ds2/authenticate) for further steps in this flow.

Scenario 2: Client supports only 3DS 2

When the client supports only 3DS 2, set the values of both clientStartProtocolVersion and clientEndProtocolVersion fields to 2.1.0 in the /3ds2/lookup request. The 3DS Server checks if the acctNumber supports 3DS 2, and if supported, it returns the /3ds2/lookup response.

Sample lookup request and response

For further steps in this flow, see Direct integration with the 3DS Server.

Scenario 3: Client supports 3DS 2 and 3DS 1 fallback is enabled

In this scenario, the value of clientStartProtocolVersion is set to 1.0.2 and the value of clientEndProtocolVersion is set to 2.1.0 or later.

• If the acctNumber supports 3DS 2, the 3DS Server returns the /3ds2/lookup response.

  Sample lookup request and response

  For further steps in this flow, see Direct integration with the 3DS Server.

• If the acctNumber does not support 3DS 2 but supports 3DS 1, the 3DS Server returns the following /3ds2/lookup response.

  See Step 5 - Send additional cardholder data for transaction authentication (/3ds2/authenticate) for further steps in this flow.

Example request

{
  "messageId": "sample-test",   
  "acctNumber": "4900000000000003",
  "doBinLookup" : false, 
  "clientStartProtocolVersion": "1.0.2",        // Oldest 3DS version supported by the client.
  "clientEndProtocolVersion" : "2.1.0"         // Most recent 3DS version supported by the client
}

Description of lookup request and response parameters

Example response if 3DS 1 fallback is enabled and the acctNumber supports 3DS 1

{
  "messageId": "sample-test",
  "threeDSServerTransID": "f00a98c3-2d39-4b33-a6f2-1759d2ede222",
  "dsStartProtocolVersion": "1.0.2",
  "dsEndProtocolVersion": "1.0.2",
  "acsStartProtocolVersion": "1.0.2",
  "acsEndProtocolVersion": "1.0.2",
  "serverStartProtocolVersion": "1.0.2",              // Oldest 3DS version supported by the 3DS Server.
  "serverEndProtocolVersion": "2.1.0"                 // Most recent 3DS version supported by the 3DS Server.
}

Description of lookup request and response parameters

• If the acctNumber does not support 3DS 2 or 3DS 1

The 3DS Server first attempts 3DS 2 authentication and then checks for 3DS 1 support. When both checks are false, it returns an error.

Example response if 3DS 1 fallback is enabled, but the acctNumber does not support 3DS 1 or 3DS 2 (i.e., an error)

{
  "messageId": "sample-test",
  "serverStartProtocolVersion": "1.0.2",
  "serverEndProtocolVersion": "2.1.0",
  "error": {
    "messageType": "Erro",
    "messageVersion": "2.1.0",
    "threeDSServerTransID": "67b76006-c6a6-4956-915b-0df41fc47b83",
    "errorCode": "305",
    "errorComponent": "S",
    "errorDescription": "Account number not supported",
    "errorDetail": "Account number not supported by 3DS. Validate the account number: 40XXXXXXXXXX0005"
    }
}

Step 5: Send additional cardholder data for transaction authentication

Use the POST /3ds2/authenticate call to send additional cardholder details to the 3DS Server. The messageVersion (optional), clientStartProtocolVersion, and clientEndProtocolVersion field values in the authenticate request help the 3DS Server to decide whether to process the transaction using 3DS 2 or 3DS 1 protocol.

To enable fallback to 3DS 1, set the value of clientStartProtocolVersion to 1.0.2 and the value of clientEndProtocolVersion to 2.1.0 in the authenticate request. If 3DS 1 fallback is enabled, the 3DS Server converts the aReq to VEReq and completes the 3DS 1 verify enrollment flow.

• VEReq (Verify Enrollment Request): determines whether 3DS 1 authentication is available for a particular PAN/acctNumber.
• VERes (Verify Enrollment Response): advises the merchant whether 3DS 1 authentication is available for a particular PAN/acctNumber.

Sample URL

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

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

The following scenarios are possible when you send the /3ds2/authenticate request.

Scenario 1: Client only supports 3DS 1

If you want the 3DS Server to always fallback to 3DS 1 for transaction authentication, you must set the following fields to 1.0.2 in the authenticate request: messageVersion and clientStartProtocolVersion.

In the background, the 3DS Server will convert the 3DS 2 authenticate request (aReq) to 3DS 1 Verify Enrollment Request (VEReq) and send it to the ACS to complete the 3DS 1 verify enrollment call. The 3DS Server will convert the Verify Enrollment Response (VERes) from the ACS to 3DS 2 authentication response (aRes) and send it to the client. The aRes returns the acsURL that the client will redirect the customer to for challenge completion. The aRes also returns the PaReq, TermUrl, and MD that the client will send to the ACS in step 6 for 3DS 1 authentication.

Example 3DS 1 authentication request

{
    "messageId": "sample-test",
    "aReq":
    {
        "messageVersion": "1.0.2",
        "threeDSServerTransID": "ec9a5b6c-bc55-4296-aa3b-d1d762e655f2",
        "acctNumber": "4000020000000000",
        "cardExpiryDate": "2312",
        "purchaseAmount": "101",
        "purchaseCurrency": "978",
        "purchaseExponent": "2",
        "purchaseDate": "20170316141312",
        "messageCategory": "01",
        "transType": "01",
        "threeDSRequestorAuthenticationInd": "01",
        "deviceChannel": "02",
        "browserAcceptHeader": "text/html,application/xhtml+xml,applicati...",
        "browserJavaEnabled": true,
        "browserLanguage": "en",
        "browserColorDepth": "48",
        "browserScreenHeight": "400",
        "browserScreenWidth": "600",
        "browserTZ": "-240",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47..",
        "notificationURL" : "http://merchantURL/handle_3DS1_pares",     
    },
    "clientStartProtocolVersion": "1.0.2",
    "clientEndProtocolVersion": "1.0.2"
}

Example 3DS 1 authentication response

{
  "messageId": "sample-test",
  "aRes": {
    "messageType": "VERes",
    "messageVersion": "1.0.2",
    "threeDSServerTransID": "1a6076cf-eced-447a-a136-585c5ae82d06",
    "acsURL": "https://uat.acs.fraud.eu.elavonaws.com/acs/challenge/VISA",
    "xid": "549855BF4A.33C824-T1"
  },
  "PaReq": "eJxVUmFvmzA...",
  "TermUrl": "http://merchantURL.com/handle_3DS1_pares",
  "MD": "encoded64bitPaReqMsgIDandetc"
}

Scenario 2: Client only supports 3DS 2

In this scenario, the clientStartProtocolVersion and clientEndProtocolVersion fields are set to 2.1.0 or later. The 3DS Server authenticates the transaction using the 3DS 2 authentication flow.

For further steps in this flow, see Direct integration with the 3DS Server.

Scenario 3: Client supports 3DS 2 and fallback to 3DS 1 is enabled

If you want to enable 3DS 1 fallback (i.e., clientStartProtocolVersion = 1.0.2 and clientEndProtocolVersion = 2.1.0), you can optionally set the messageVersion field to 2.1.0. If you do not include this field in the authenticate request, the 3DS Server sets the value to 2.1.0 by default.

The 3DS Server returns one of the following responses:

• If the acctNumber supports 3DS 2, the 3DS Server authenticates the transaction using the 3DS 2 authentication flow. For further steps in this flow, see Direct integration with the 3DS Server.

• If the acctNumber does not support 3DS 2 but 3DS 1 fallback is enabled, then the 3DS Server authenticates the transaction using the 3DS 1 authentication flow.

  In the background, the 3DS Server will convert the 3DS 2 authenticate request (aReq) to 3DS 1 Verify Enrollment Request (VEReq) and send it to the ACS to complete the 3DS 1 verify enrollment call. The 3DS Server will convert the Verify Enrollment Response (VERes) from the ACS to 3DS 2 authentication response (aRes) and send it to the client. The aRes returns the acsURL that the client will redirect the customer to for challenge completion. The aRes also returns the PaReq, TermUrl, and MD that the client will send to the ACS in the next step (Send details to ACS for challenge completion and receive PaRes from the ACS) for 3DS 1 authentication.

  See the example request and response in Step 5 Scenario 1.

Scenario 4: Client supports 3DS 2 and fallback to 3DS 1 is also enabled, but acctNumber does not support 3DS 2 or 3DS 1

The 3DS Server returns the following error response.

Example response

{
  "messageId": " db09f94a-12eb-44e9-ad3b-87a23370b205",
  "error": {
    "messageType": "Erro",
    "messageVersion": "2.1.0",
    "threeDSServerTransID": "8ef7c99e-72e5-4d66-8a84-229cd9f925d9",
    "errorCode": "305",
    "errorComponent": "S",
    "errorDescription": "Invalid transaction data",
    "errorDetail": "Account number not enrolled in 3DS 1.0. Please register card with Issuer to proceed.",
    "errorMessageType": "AReq"
  }

Step 6: Send details to ACS for challenge completion

If the acctNumber support 3DS 1, perform this step to complete 3D Secure (3DS) Authentication. The challenge and validation flow for 3DS 1 is different from the 3DS 2 flow. In 3DS 1, it is the client’s responsibility to redirect the customer’s browser to the acsURL for challenge completion. The ACS handles the challenge completion directly with the cardholder and will send the Payer Authentication Response (PaRes) back to the client for validation.

1. To initiate a challenge, the client should FORM-POST these three fields to the acsURL: PaReq, TermUrl, and MD via a redirect from the user’s browser.
   The PaReq and MD contain encrypted data required for the ACS to complete authentication. The TermUrl is the return address that the ACS will redirect the customer to after the 3DS authentication. As mentioned in the prerequisites, the client can also pass in the URL of their challenge-response receiver page as the TermUrl.

2. After the cardholder authenticates with the issuer directly, the ACS will send the cardholder back to the page provided in the TermUrl with an HTTP Post. The ACS will also send the Payer Authentication Response (PaRes) and the MD to the TermUrl. Note that the ACS sends the PaRes to the TermUrl even if the authentication fails.

Step 7: Validate the PaRes to obtain authentication results

Following authentication, the ACS will redirect the cardholder to the TermUrl sent in step 6 for challenge completion. To validate the PaRes and obtain the final authentication result, send the /3ds2/validate request to the 3DS Server and pass in the PaRes and MD in the request body.

In the background, the 3DS Server will complete the validate PaRes call. The 3DS Server will decode the PaRes and validate the response against the MD to complete 3DS validation. After validation, the 3DS Server will return the results of the validation (rReq) and the transaction status (transStatus) for the client to complete the transaction. Depending on the validation result, the client can authorize or decline the transaction.

POST /3ds2/validate

Sample URL

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

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

Sample request

{
 "PaRes" : "JzVWFmPo0qyCXszacKQNUK/b8L3vRy2rRuHX9Pg+……",
 "MD" : "eyJwYVJlcU1zZ0l…."
}

Sample response of a successful validation

{
  "messageId": "sample-test",
  "threeDSServerTransID": "1a6076cf-eced-447a-a136-585c5ae82d06",
  "valid": true,
  "xid": "574FADF181.D4993A-T1",
  "cavvAlgorithm": "2",
  "rReq": {
       "messageType": "RReq",
       "messageVersion": "1.0.2",
       "threeDSServerTransID": "1a6076cf-eced-447a-a136-585c5ae82d06",
       "authenticationValue": "rPTpf2gUHkTkoSOmN5aTJkfcgDs=",
       "eci": "05",
       "transStatus": "Y"
    }
}

For more information on liability shift and next steps for merchants for different transStatus, see Test your integration. Note that in a 3DS 1 transaction, the response returns the transStatus value as either of the following: Y, N, U, A. The eci and authenticationValue fields are returned in the response only for transStatus = Y or A.

Sample response of a failed validation

{
  "messageId": "sample-test",
  "threeDSServerTransID": "2ac6ae1b-e388-4a4d-9842-47bda005936a",
  "valid": false
}

Field descriptions of 3DS 1 specific elements

Element Length | Type | Required	Description
messageType 5 | String | Required	Message type Identifies the type of message that is passed. Valid values for 3DS 1: • VEReq Valid values for 3DS 2: • aReq • aRes • rReq • rRes
messageVersion 5-8 | String | Required	Message version The 3DS protocol version used by all components to process the 3D Secure transaction. Set by the 3DS Server, which originates the protocol with the authentication request message. Note:If you want the 3DS Server to always fallback to 3DS 1, set it to 1.0.2 in the authenticate request. For 3DS 1, it is 1.0.2 For 3DS 2, it is 2.1.0
xid 28 | Base64 | Required	Unique purchase ID. Returned from the 3DS Server.
enrolled Boolean | Required	Indicates whether the card is enrolled in 3DS 1 or not. Returned from the 3DS Server. Valid values: • true • false
acsURL Max 2048 | String | Conditional	ACS URL The ACS URL used to complete the 3DS 1 challenge flow. Client must redirect the cardholder to this URL for challenge completion.
PaReq Base64 | ANS | Required	Payer authentication request The PaReq is sent to the ACS by the 3DS Server, which uses the information in the aReq and converts it to the PaReq. It contains the data required to attempt cardholder authentication.
TermUrl String | Required	Indicates the URL that will be notified of the challenge result by ACS. The TermUrl is the URL sent in the aReq.notificationURL field in the authentication request.
MD 0-1024 ANS | String | Conditional	Merchant data A 64bit encoded JSON unique reference to identify if the 3D Secure request is genuine. It is sent to the ACS for challenge completion.
cavv 28 | Base64 | Conditional	Cardholder Authentication Verification Value. In case of a direct integration with the 3DS Server, the server returns an authenticationValue field instead of cavv.
cavvAlgorithm 0-1 | String | Conditional	Indicates the algorithm used to generate the Cardholder Authentication Verification Value. Note: If the cavv field is included, the cavvAlgorithm field must also be included. If the cavv field is missing, the cavvAlgorithm field must also be missing.
eci 0-2 | String | Conditional	Electronic commerce indicator Payment Scheme specific element that represents the value of the ECI, as determined by the ACS. Note: Required for Visa and MasterCard transactions when the value of statusCode is Y or A
statusCode 1 | String | Required	Indicates the transaction authorization status of the transaction. Valid values: • Y - Success • N - Failed or transaction declined • A - Attempted • U - Unavailable
PaRes Base64 | Required	Payer authentication response The PaRes message is sent by the ACS in response to the PaReq, regardless of whether authentication is successful.

• previous 3RI Authentication - Sample Request and Response
• next Travel industry message extension