Direct integration to 3DS Server

On this page:

Use the information on this page to support 3D Secure 2 authentication on your website. In this integration option, all requests are sent by your server. A transaction can go through a frictionless flow or a challenge flow depending on the authentication results from the issuer. To support these flows, you must build your client-side and server-side implementations.

To use the 3DS Web SDK, see 3DS Web SDK Overview.

High-level steps for integrating with Elavon’s 3DS server for a transaction authentication

  1. Complete the setup prerequisites

  2. Collect cardholder data

  3. (Optional) Initiate the 3D Secure 2 lookup request by sending the card holder’s card/account number to Elavon’s 3DS Server

  4. If the card/account number is supported for 3D Secure 2, send additional cardholder data to the 3DS Server for authentication

  5. Verify the authentication response received from Elavon’s 3DS Server[/

Authentication workflows

A diagram explaining how the request and responses flow among the client and the servers involved in 3DS authentication of a transaction

Figure caption: Frictionless and challenge workflow in a server-to-server integration

Prerequisites for sending the cardholder data for 3D Secure 2 authentication

  • To request 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

    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.

3D Secure 2 Authentication steps for each transaction

Step 1: Collect cardholder data

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

(Optional) Step 2: Send cardholder’s card/account number to verify support for 3D Secure 2 (/3ds2/lookup)

Send the card holder’s card/account number to Elavon’s 3DS Server to:

  • verify if the card used by the cardholder for the transaction supports 3D Secure 2

  • retrieve key characteristics of the card used in the transaction such as the card BIN, scheme, brand, country, and currency where the card has been issued, if the card is a debit or a credit card, etc. The BIN is the first four, six, or more digits of the card number. The /3ds2/lookup request uses the BIN information to scan an internal repository of data to retrieve more details about the card being used.

The BIN lookup parameters along with the fact the card supports 3DS 2 authentication can help you understand which version of the 3D Secure 2 the card supports.

If you do not send the /lookup request and send the (/authenticate (Step 4)) request directly, the /authenticate response will return an error message if the issuer does not support the requested 3D Secure version.

Use the following links for a sample /3ds2/lookup request, response, and parameters description:

(Optional) Step 3: Verify the /3ds2/lookup response

The 3DS Server uses the ACS Start Protocol Version, ACS End Protocol Version, DS Start Protocol Version, and DS End Protocol Version returned in the /lookup response to verify that the ACS and the DS support the 3DS protocol version used by the 3DS Server. It uses the ACS Information Indicator to identify the features that the account supports.

Verify the /3ds2/lookup response and use the scenarios in table 1 to help you decide the next step.

Table 1: /lookup response scenarios

ScenarioNext Step
Scenario 1: If the /3ds2/lookup response does not have the version fields (dsStartProtocolVersion, dsEndProtocolVersion, acsStartProtocolVersion, acsEndProtocolVersion) or the values of these fields are 1.0.2, it means that the card number (PAN) does not support 3DS 2 authentication.You cannot proceed with 3DS 2 authentication for this transaction. The 3DS server returns an error message.
Scenario 2: If the /3ds2/lookup response contains the version fields (dsStartProtocolVersion, dsEndProtocolVersion, acsStartProtocolVersion, acsEndProtocolVersion) and their values are either 2.1.0 or later, but the threeDSMethodURL field is not present.Proceed to step 4.
If the threeDSMethodURL field is not present, it means that the ACS does not support 3DS Method. In this scenario, you can directly send the /3ds2/authenticate request.
Scenario 3: If the /3ds2/lookup response contains the version fields (dsStartProtocolVersion, dsEndProtocolVersion, acsStartProtocolVersion, acsEndProtocolVersion), their values are either 2.1.0 or later, and the threeDSMethodURL field is also present.If the threeDSMethodURL field is present, invoke the 3DS Method before you send the /3ds2/authenticate request. The browser will need to connect to the ACS (or a designated entity) mentioned in the threeDSMethodURL value to gather browser and device information. To facilitate browser and device information collection, render a hidden HTML iframe in the cardholder’s browser (see sample iframe code for contents of the iframe). In this iframe, create a form that is auto-submitted when the cardholder’s response is loaded in the iframe. The auto submission of this form will post the threeDSMethodData field value to the threeDSMethodURL.
Proceed to step 4 when you receive either a successful completion notification from the 3DS Server (or notification on the custom URL, if you have set one) or if you do not receive a response after 10 seconds of sending the HTTP POST form.
This step is optional, but we strongly recommend you to perform this step to increase the chances of a frictionless authentication.

Sample iframe code

<html>
 <body onload='document.forms[0].submit()'>
    <form method=POST action='value of the threeDSMethodURL in the /3ds2/lookup response'>
      <input type=hidden name='threeDSMethodData' value='value of the threeDSMethodData field in the /3ds2/lookup response'>
    </form>
  </body>
</html>

Step 4: Submit cardholder data to the 3DS Server to initiate the 3DS authentication process (/3ds2/authenticate)

If the card used in the transaction supports 3D Secure 2, submit the required authentication information to Elavon’s 3DS Server. The 3DS Server in turn creates an authentication request and sends it to the ACS. 

Review table 2 to understand how these three fields in the /authenticate request help the 3DS Server to decide whether to follow 3DS 2.2 or 3DS 2.1 authentication flow: messageVersion, clientStartProtocolVersion, and clientEndProtocolVersion.

Table 2: 3DS Server Fallback Strategy

messageVersionclientStartProtocolVersionclientEndProtocolVersion3DS Server Fallback Strategy
1.0.21.0.21.0.23DS Server returns an error.
1.0.21.0.22.1.0 or 2.2.03DS Server returns an error.
2.1.0 or 2.2.01.0.21.0.23DS Server returns an error.
2.1.01.0.22.1.0 or 2.2.0Check support for 3DS 2.1. If not supported, the 3DS Server returns an error.
2.1.02.1.02.1.0Check support for 3DS 2.1. If not supported, return an error.
2.1.02.1.02.2.0Check support for 3DS 2.1. If not supported, return an error.
2.2.01.0.22.2.0Check support for 3DS 2.2 first. If not supported, check support for 3DS 2.1. If 3DS 2.1 is not supported, the 3DS Server returns an error.
2.2.02.1.02.1.0Error response
2.2.02.2.02.2.0Check support for 3DS 2.2. If not supported, return an error.
2.2.02.1.02.2.0Check support for 3DS 2.2 first. If 3DS 2.2 is not supported, fall back to 3DS 2.1. If 3DS 2.1 is not supported, return an error.

note

  • messageVersion is an optional field and if you do not manually specify a value in the authenticate request, the 3DS Server sets its default value to 2.1.0.

    • If the 3DS Server falls back the request to 2.1.0, the issuer ignores all fields that are specific only to the 3D Secure 2.2.0.

  • The request will not fall back from 2.2.0 to 2.1.0

    • if you send a value specific to the 2.2.0 spec only in an existing field (a field that was present in the 2.1.0 spec as well). For example, if you set the field value of the threeDSRequestorAuthenticationInd field (present in both the 2.1.0 and the 2.2.0 spec) to 07 (billing agreement). Here the field value 07 is specific to 2.2.0 only.

    • if one or more fields that are required in the 2.1.0 spec but are optional in the 2.2.0 spec are missing in the authentication request. For example, for deviceChannel = 02, the browserColorDepth, browserScreenHeight, browserScreenWidth and browserTZ fields are always required, but in the 2.2.0 spec these fields are optional if browserJavascriptEnabled = false.

Use the following links to refer to the sample authentication request, response, and parameters description.

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.

note

By default, the 3DS Server receives the callbacks from the ACS. But if you want to opt-out from the default challenge callback functionality and implement your own challenge-response landing page, set the value of the notificationURL field in the /3ds2/authenticate request 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. To fetch the challenge result data from the ACS, you will have to send the /3ds2/validate request (step 7b) instead of the /3ds2/challenge_result request.

Step 5: Verify the 3DS authentication response from the 3DS Server

Verify the value of the transStatus field in the /3ds2/authenticate response sent by the 3DS Server because it determines your next step. Review the information in table 3 to understand the next steps for each transStatus value.

If the acctNumber or the issuer doesn’t support 3D Secure 2, the 3DS Server returns an error.

Table 3: Description of the transStatus field value in /authenticate response

transStatusDescriptionLiability shiftNext stepExample scenario
YIssuer has authenticated the customer’s data. You can use the transStatus, authenticationValue, and eci field values to authorize the transaction. The flow is considered frictionless and the 3DS processing will end at this step.Card issuerMerchant can use the eci and authenticationValue in the authentication response to proceed to card authorization.You get this value in case of a successful authentication or a frictionless flow.
AIssuer has not authenticated the transaction, but a proof of authentication attempt (authenticationValue) was generated. You can use the transStatus, authenticationValue, and eci field values to authorize the transaction. The 3DS processing will end at this step.Card issuerMerchant can use the eci and authenticationValue in the authentication response to proceed to card authorization.You get this value in case of an attempted authentication.
IIssuer acknowledges that the request was sent for informational purposes only and did not need a challenge.Not applicableMerchant should store the authenticationValue and eci field values if included in the response.You get this value when you send the request only for information and do not request for authentication. To indicate this in the authentication request, you sent a value of 05, 06, or 07 in the threeDSRequestorChallengeInd field.
CIssuer needs more information to authenticate the cardholder. The flow is considered a challenge flow. Proceed to step 6.Not applicable; Authentication in progressMerchant should proceed with the challenge to get the final authentication result.You get this value when the issuer needs more authentication data from the cardholder.
NIssuer has not authenticated the transaction, or could not verify the account, or denied the transaction.No liability shiftIf you get this value, verify the value in the transStatusReason field. Based on the value received, you can do either of the following:
  • Try to send the authentication request again
  • Request the customer for another form of payment
  • Decline the transaction
  • Move forward with authorization at your own risk
You get this value in case of authentication processing errors such as when the cardholder fails all challenges to prove cardholder identity.
UIssuer has not authenticated the transaction or verified the account due to a technical or another problem.No liability shiftIf you get this value, verify the value in the transStatusReason field. Based on the value received, you can do either of the following:
  • Try to send the authentication request again
  • Request the customer for another form of payment
  • Decline the transaction
  • Move forward with authorization at your own risk
You get this value in case of technical errors such as when the ACS is not reachable.
RIssuer is rejecting the authentication or account verification and requesting that authorization not be attempted.No liability shiftIf you get this value, verify the value in the transStatusReason field. Based on the value received, you can do either of the following:
  • Try to send the authentication request again
  • Request the customer for another form of payment
  • Decline the transaction
  • Move forward with authorization at your own risk
You get this value in case the issuer rejects authentication and requests that authorization should not be attempted.

note

The liability shift is only for disputed transactions or chargebacks. Use the following information related to liability shift and next steps for merchants as a reference. These can differ for each card scheme and each issuer might have different criteria for liability shift.

Step 6: If transStatus = C, create an iframe to facilitate the challenge process between the issuer and the cardholder

Perform this step only if you received transStatus = C in Step 5.

The challenge process requires the cardholder to send the authentication data to the issuer directly. Therefore, to challenge the cardholder, you need to create an iframe and populate it with the creq value received in the authentication response. This iframe will autosubmit the creq to the acsURL.

The issuer will validate the creq data and create an authentication user interface (ACS UI) that is loaded on the iframe.

The cardholder will enter the authentication data requested by the issuer in the form that is loaded on this iframe and submit the authentication data to the issuer. The issuer will verify the authentication data and send the challenge response to the browser in an HTML form that will be auto-submitted to the notificationURL field value mentioned in the authentication request sent by the merchant (/3ds2/authenticate).

note

By default, the 3DS Server receives the callbacks from the ACS. But if you want to opt-out from the default challenge callback functionality and implement your own challenge-response landing page, set the value of the notificationURL field in the /3ds2/authenticate request 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. To fetch the challenge result data from the ACS, you will have to send the /3ds2/validate request (step 7b) instead of the /3ds2/challenge_result request.

To facilitate the challenge process, perform the following steps:

  1. Select the size of the HTML iframe from one of the window sizes specified in the challengeWindowSize data element: 

    • If you are building a static UI with client-side restriction on the iframe sizing, then use one of the following options for the challengeWindowSize parameter:

      • 01 = 250 x 400
      • 02 = 390 x 400
      • 03 = 500 x 600
      • 04 = 600 x 400

    • If you are opting for a responsive design that lets the issuer to dynamically scale the content, then use the following option for the challengeWindowSize parameter:

      • 05 = Full screen

  2. Copy the creq value from the authentication response. The creq request JSON object should be Base 64 encoded.

    Sample creq JSON encoded data

    eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI4YTg4MGRjMC1kMmQyLTQwNjctYmNiMS1iMDhkMTY5MGIyNmUiLCJhY3NUcmFuc0lEIjoiODRiMmU5YTYtYjEwMi00OGRiLTkzZjAtNjBlZmFmYjk5Nzc0In0=

  3. Render an HTML iframe in the cardholder’s browser, and generate an HTTP POST through the iframe to the acsURL that was received in the authentication response message.

    Sample iframe code

    <html>
  <body onload='document.forms[0].submit()'>
    <form method=POST action='https://value-of-the-acsURL-in-the-/3ds2/authenticate-response'>
      <!-- creq value is the encrypted value of the creq field in the /3ds2/authenticate response -->
      <input type=hidden name='creq' value= 'eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI4YTg4MGRjMC1kMmQyLTQwNjctYmNiMS1iMDhkMTY5MGIyNmUiLCJhY3NUcmFuc0lEIjoiODRiMmU5YTYtYjEwMi00OGRiLTkzZjAtNjBlZmFmYjk5Nzc0In0='>
    </form>
  </body>
</html>

Step 7: Verify the challenge completion response using either step 7a or step 7b

Step 7a: If you sent the 3DS Server URL as the notificationURL in the /3ds2/authenticate request, verify the challenge response /3ds2/challenge_result/{threeDSServerTransID}

If you received transStatus = C or D in the /authenticate response, verify the challenge completion response from the 3DS Server using the threeDSServerTransID value from the authentication response (/3ds2/authenticate).

note

By default, the 3DS Server receives the callbacks and notifications on the notificationURL populated by the 3DS Server in the authentication request (/3ds2/authenticate).

Use the /3ds2/challenge_result/{threeDSServerTransID} request to retrieve the result of the challenge completion. Use the following links to see a sample challenge result request, response, and parameters description:

After you verify the challenge result, close the challenge window by refreshing the parent page and removing the HTML iframe.

If the challenge completion result is successful (transStatus = Y), use the transStatus, authenticationValue, and eci field values to complete the 3DS authentication process.

Step 7b: If you specified a different notificationURL in the /3ds2/authentication request, verify the challenge response from the ACS ( /3ds2/validate)

If you opted out from the default challenge callback functionality and implemented your own challenge-response landing page by setting the value of the notificationURL field in the /3ds2/authenticate request to a custom URL, you must monitor notifications sent by the ACS to this page. To fetch the challenge result data from the ACS, send the /3ds2/validate request (step 7b) instead of the /3ds2/challenge_result request (step 7a).

note

Before you send the /3ds2/validate request, the landing page should accept POST request from the ACS with FORM parameter named cres. After you get the cres value from the ACS, use the messageId and the cres in the /3ds2/validate request. The /3ds2/validate response will have the rReq data with the challenge result or the final authentication result. You do not need to send any additional request to the 3DS Server i.e., a /3ds2/challenge_result request (step 7a).

Use the following links to see a sample validate challenge result request, response, and parameters description:

If the challenge completion result is successful (transStatus = Y), use the transStatus, authenticationValue, and eci field values to complete the 3DS authentication process.

Related topics