Direct integration to 3DS Server

error_outline
note

EMV 3D Secure 2.1 is a new offering by Elavon. If you have identified any errors or gaps in the content, please contact: #SEDevPortalSupport@elavon.com

Overview

Use the information on this page to support 3D Secure 2.1 authentication on your website. 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.

Elavon also supports fallback to 3DS 1 in addition to 3DS 2.1. For steps to enable 3DS 1 fallback while integrating directly to the 3DS Server, see 3DS 1 Fallback . If you are integrating through 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. Prepare your website’s payment page for 3D Secure 2.1 authentication

  3. Collect card holder data

  4. Initiate the 3D Secure 2.1 lookup request by sending the card holder's card/account number to Elavon's 3DS Server

  5. If the card/account number is supported for 3D Secure 2.1, send additional card holder data to the 3DS Server for authentication

  6. Verify the authentication response received from Elavon’s 3DS Server

Integration workflows

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

Prerequisites for integrating the 3DS 2.1 feature to your website’s payment page

  • 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.

error_outline
important

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

  • Set up a test and a production environment.

For more details on authentication mechanisms supported by Elavon for 3D Secure, see Authentication . If you are integrating using the 3DS Web SDK, see 3DS Web SDK Overview .

Preparing your website’s payment page for 3DS 2.1 authentication

Before you begin with the 3DS 2.1 transaction authentication flow, you must perform the following steps to prepare your website’s payment page to support the integration with the 3DS Server. Note that you need to perform these steps just once and do not need to repeat these for every transaction.

error_outline
note

If you are using Elavon's 3DS Web SDK, you do not need to perform this step. For more details on using 3DS Web SDK, see 3DS Web SDK Integration

Event listener code for callbacks

To integrate the 3DS 2.1 flow into your website’s payment page, register this event listener code on your payment page for callbacks related to the threeDSmethodURL posts and completion of challenge flow.

Sample code to handle method call and challenge completion event

<script>
function onMessage(e) {  
console.log('onMessage: data='+JSON.stringify(e.data));  
if (e.data.src === "method_notify") {  
onMethodComplete(e.data.param);  
} else if (e.data.src === "challenge_notify") {  
onChallengeComplete(e.data.param);  
}  
}  

function onMethodComplete(param) {  
console.log('onMethodComplete: param: ' + JSON.stringify(param));  
}  

function onChallengeComplete(param) {  
console.log('onChallengeComplete: param: ' + JSON.stringify(param));  
}  

if (window.addEventListener) {  
window.addEventListener('message', onMessage, false);  
} else if (window.attachEvent) {  
window.attachEvent('onmessage', onMessage, false);  
}  
</script>

error_outline
note

By default, the 3DS Server receives the callbacks from the ACS. To receive notifications on a different server, you can send the field value of the following fields as a custom URL of the server where you want to get the notifications. In such cases, you are responsible for handling notifications and continuing on with the 3DS flow.

  • To receive the notification of 3DS Method completion from the ACS (issuer) on a different server, send a custom URL as the value of the threeDSMethodNotificationURL field in the /3ds2/lookup request ( step 2 ).

  • To opt out from the default challenge callback functionality and implement your own challenge response landing page, send a custom URL as the value of the notificationURL field in the /3ds2/authenticate request to a custom URL, where you can receive and monitor notifications. 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 ).

3DS Authentication flow for each transaction

Step 1: Collect cardholder data

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

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

To verify if the card used by the cardholder for the transaction supports 3D Secure 2.1, send the card holder’s card/account number to Elavon’s 3DS Server. You can also use the /3ds2/lookup request to 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, and so on. 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.1 authentication can help you decide whether you want to proceed with the 3DS authentication of the transaction.

Use the /3ds2/lookup request to send the acctNumber to the 3DS Server. Use the following links for a sample /3ds2/lookup request, response, and parameters description.

/3ds2/lookup: Sample request and response and Description of request and response parameters

For additional /3ds2/lookup scenarios, see Test scenarios - Sample /3ds2/lookup scenarios

Step 3: Verify the /3ds2/lookup response

Verify the /3ds2/lookup response from the 3DS Server to determine the next step. See the following possible scenarios:

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.1 authentication.

Next step: You cannot proceed with 3DS 2.1 authentication for this transaction. However, if the clientStartProtocolVersion was set to 1.0.2 in the /3ds2/lookup request, the 3DS Server attempts fallback to 3DS 1 to authenticate the transaction.

For the next steps in the 3DS 1 fallback flow, see 3DS 1 Fallback . But if you do not support 3DS 1, you can choose to use a non-3DS payment authorization at your own risk.

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.

Next step: Proceed to step 4 .
In a browser-based flow, such as integration with the 3DS Server using the Web SDK, you do not need to create the hidden iframe. You can directly proceed with 3DS 2.1 authentication.

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.

Next step: 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. The value of these fields are present in the /3ds2/lookup response.
Proceed to step 4 when you receive either a successful completion notification from the 3DS Server (or a 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.

error_outline
note

If you are currently not using 3D Secure 1 eMPI plug-in offered by Elavon and are interested in using the 3D Secure 1 services, see the Converge Documentation on developer.elavon.com or contact your sales representative.

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 3DS authentication process (/3ds2/authenticate)

If the card used in the transaction supports 3D Secure 2.1, 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. 

Use the /3ds2/authenticate request to send the cardholder information to the 3DS Server. Use the following links for a sample authentication request, response, and parameters description.

/3ds2/authenticate: Sample request and response and Description of request and response parameters

To increase the chances of a successful authentication, include information for all required and optional fields in the authentication request you send to the 3DS Server.

error_outline
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 on 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 7a ).

For additional /3ds2/authenticate scenarios, see Test scenarios - Sample /3ds2/authenticate scenarios

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 following scenarios to understand the next steps for each transStatus value.

error_outline
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 a different criteria for liability shift.

transStatus = Y

Description: Issuer 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.

Liability shift: Card issuer

Next step: Merchant can use the eci and authenticationValue in the authenication response to proceed to card authorization.

Example scenario: You get this value in case of a successful authentication or a frictionless flow.

transStatus = A

Description: Issuer 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.

Liability shift: Card issuer

Next step: Merchant can use the eci and authenticationValue in the authenication response to proceed to card authorization.

Example scenario: You get this value in case of an attempted authentication.

transStatus = C

Description: Issuer needs more information to authenticate the cardholder. The flow is considered as a challenge flow. Proceed to step 6 .

Liability shift: NA; Authentication in progress

Next step: Merchant should proceed with the challenge to get the final authentication result.

Example scenario: You get this value when the issuer needs more authentication data from the cardholder.

transStatus = N

Description: Issuer has not authenticated the transaction, or could not verify the account, or denied the transaction.

Liability shift: No liability shift

Next step: If 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

  • Ask the customer for another form of payment

  • Decline the transaction

  • Move forward with authorization at your own risk

Example scenario: You get this value in case of authentication processing errors such as when the cardholder fails all challenges to prove cardholder identity.

transStatus = U

Description: Issuer has not authenticated the transaction or verified the account due to a technical or another problem.

Liability shift: No liability shift

Next step: If you get this value, verify the value in the transStatusReason field. Based on the value received, you can do either of the following:

  • Send the authentication request again

  • Ask the customer for another form of payment

  • Decline the transaction

  • Move forward with authorization at your own risk

Example scenario: You get this value in case of technical errors such as when the ACS is not reachable.

transStatus = R

Description: Issuer is rejecting the authentication or account verification and requesting that authorisation not be attempted.

Liability shift: No liability shift

Next step: If 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

  • Ask the customer for another form of payment

  • Decline the transaction

  • Process the transaction at your own risk; however, note that no liability shift will occur

Example scenario: You get this value in case the issuer rejects authentication and requests that authorization should not be attempted.

Step 6: Create an iframe to facilitate the challenge process between the issuer and the cardholder

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 and the threeDSSessionData values received in the authentication response. This iframe will auto submit the creq and threeDSSessionData 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).

error_outline
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 on 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 7a ).

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 allows the issuer content to scale dynamically, then use the following option for the challengeWindowSize parameter:

      • 05 = Full screen
  2. Generate the creq request and post it to the ACS. The creq request JSON object should be Base 64 encoded.

    Sample creq JSON encoded data

      eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI4YTg4MGRjMC1kMmQyLTQwNjctYmNiMS1iMDhkMTY5MGIyNmUiLCJhY3NUcmFuc0lEIjoiODRiMmU5YTYtYjEwMi00OGRiLTkzZjAtNjBlZmFmYjk5Nzc0In0=

    Sample creq JSON decoded data

      {
        "messageType": "CReq",
        "messageVersion": "2.1.0",
        "threeDSServerTransID": "c77376c8-f545-47a9-9029-d91f516c4360",
        "acsTransID": "2ef1386a-93ee-452c-aec9-03bae6dd3ea6",
        "challengeWindowSize": "01"
      }
  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='value of the acsURL in the /3ds2/authenticate response'>
            <input type=hidden name='creq' value= eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI4YTg4MGRjMC1kMmQyLTQwNjctYmNiMS1iMDhkMTY5MGIyNmUiLCJhY3NUcmFuc0lEIjoiODRiMmU5YTYtYjEwMi00OGRiLTkzZjAtNjBlZmFmYjk5Nzc0In0='></p>
    <p><!-- creq value is the encrypted value of the creq field in the /3ds2/authenticate response -->
    <input type=hidden name='threeDSSessionData'  value='optional-merchants-session-data'>
          </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}

Verify the challenge completion response from the 3DS Server using the threeDSServerTransID value from the authentication response (/3ds2/authenticate).

error_outline
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:

/3ds2/challenge_result/{threeDSServerTransID}: Sample request and response and Description of request and response parameters

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), authorize the payment using the transStatus, authenticationValue, and eci field values in the challenge completion response (/3ds2/challenge_result/{threeDSServerTransID}).

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 ).

error_outline
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 that gives you the challenge result data without performing additional calls 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:

/3ds2/validate: Sample request and response and Description of request and response parameters

Use the transStatus, authenticationValue, and eci field values to complete the 3DS authentication process.

Related topics