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. With this release, 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

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

error_outline
note

Currently the 3DS Server supports 3DS 1 transactions for only MasterCard, VISA, and AMEX.

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 get an Elavon account user ID and password, contact an Elavon sales representative.
  • Get the API key. When you sign up with Elavon, then as part of the boarding process, you will receive an API key that you can use for making API calls. You will receive separate API keys and user credentials for test and production environments.
  • Set up a test and a production environment.

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 .

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

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

error_outline
important

If you are integrating directly with the 3DS server, then to enable the 3DS 1 fallback capability, you must implement your own challenge response receiver page by specifying 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.

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)

error_outline
note

The /3ds2/lookup call returns the 3DS version the acctNumber supports and the BIN information. If you do not need this information, send the /3ds2/authenticate request ( See Step 5 ).

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

https://uat.gw.fraud.eu.elavonaws.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.

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.

Enable fallback to 3DS 1 by setting the value of clientStartProtocolVersion to 1.0.2 and the value of clientEndProtocolVersion to 2.1.0 in the authenticate request. If 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

https://uat.gw.fraud.eu.elavonaws.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 following fields to 1.0.2 in the authenticate request: messageVersion and clientStartProtocolVersion.

error_outline
note

The default value of the messageVersion field is 2.1.0. If you do not set this field to 1.0.2, but you set the clientStartProtocolVersion field to 1.0.2, the 3DS Server does not attempt a fallback to 3DS 1 and returns an error response.

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

error_outline
note

Set the notificationURL to a location where you want to receive the PaRes (payer authentication response). If you do not specify a custom URL, by default, the TermUrl is set to the 3DS Server URL (https://gw.fraud.eu.elavonaws.com/notify/challenge_notify) in the aRes. However, you can still send a custom URL as the TermUrl for ACS redirect in step 6 even if you did not set a notificationURL in the authenticate request.

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.

error_outline
note

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.

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.

error_outline
note
  • If you enable 3DS 1 fallback but you set the messageVersion field to 1.0.2, the 3DS Server only attempts a fallback to 3DS 1.

  • If the 3DS 2 service encounters an error and 3DS 1 fallback is enabled, the 3DS Server does not fail the transaction and begins the 3DS 1 authentication of the transaction. The fallback is triggered only for valid authentication requests (includes all required fields and has valid field values) that failed.

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

error_outline
note

Elavon could not perform a 3DS check for this transaction. Integrator can still process the transaction at their own risk and liability.

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 authentication 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 will 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

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

Sample request

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

error_outline
note

The PaRes and MD are long string values. The above sample request has incomplete values.

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. However, 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
Note: Required when the value of statusCode is Y or A
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.