3DS Browser Integration Guide

This guide explains how to use Ravelin’s 3DS Server to perform 3D Secure authentication in a browser. A reference implementation is available on GitHub

Browser Flow Diagram

The 3D Secure browser flow is shown below:

Collect Browser Info

3D Secure requires that info is collected about the customer’s browser.

To collect the required browser info your front-end must call the GetBrowserInfo() function provided by the 3DS JavaScript.

An example of the browser info is shown below:

{
  "browserAcceptHeader": "text/html,application/xml",
  "browserIP": "0.0.0.0",
  "browserJavaEnabled": true,
  "browserJavascriptEnabled": true,
  "browserLanguage": "en",
  "browserColorDepth": "24",
  "browserScreenHeight": "1080",
  "browserScreenWidth": "1920",
  "browserTZ": "0",
  "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
}

Your front-end must send the browser info to your back-end. This can be done either when sending the PAN for the Version Request or when sending the request to initiate the Authenticate Request. You may decide the format of this request.

Store the browser info on your back-end so that it can be used in the Authenticate Request.

Version Request

The Version Request determines whether the customer’s card supports 3DS 2, and which 3DS 2 version it supports.

To prepare for this request your front-end must send the customer’s primary account number (PAN) to your back-end so that you can make the Version Request. You may decide the format of this request.

This request can be performed asynchronously as soon as the customer has provided their PAN or synchronously when the customer submits their order.

You may send the PAN, and the browser info, to your back-end in the same request.

Your back-end can then use the PAN to make the Version Request. An example Version Request is shown below:

POST https://3ds.live.pci.ravelin.com/3ds/version HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "transactionId": "123-abc-XYZ",
  "pan": "4111111111111111"
}

See our 3D Secure API reference for full details of the Version Request.

The Version Response will contain the supported 3D Secure protocol versions and details required to make the Method and Authenticate requests.

An example Version Response, when the payment card supports 3D Secure 2, is shown below:

{
  "status": 200,
  "timestamp": 1600081748,
  "cardScheme": "Visa",
  "data": {
    "transactionId": "123-abc-XYZ",
    "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
    "availableVersions": ["2.1.0", "2.2.0"],
    "versionRecommendation": "2.2.0",
    "acsStartProtocolVersion": "2.1.0",
    "acsEndProtocolVersion": "2.2.0",
    "dsStartProtocolVersion": "2.1.0",
    "dsEndProtocolVersion": "2.2.0",
    "threeDSMethodURL": "https://www.example-acs.com/method",
    "acsInfoInd": ["01", "02"]
  }
}

See our 3D Secure API reference for full details of the Version Response.

If the Version Response contains a threeDSMethodURL, you must return it and the threeDSServerTransID to your front-end so that it can send a Method Request. Otherwise your back-end may proceed to send the Authenticate Request.

Method Request

The Method Request allows the Access Control Server (ACS) to collect info about the customer’s browser.

This request requires the threeDSMethodURL and threeDSServerTransID from the Version Response to be returned to your front-end.

In order to support the Method Request your back-end needs an endpoint which can receive a notification when the ACS has finished collecting info about the customer’s browser. This endpoint is referred to as the Method Notification URL.

To send a Method Request your front-end must call the SendMethodRequest(threeDSMethodURL, threeDSServerTransID, methodNotificationUrl) function provided by the 3DS JavaScript. Pass the threeDSMethodURL and threeDSServerTransID values from the Version Response, and your Method Notification URL, as arguments.

The 3DS JavaScript will create a hidden iframe which opens the threeDSMethodURL, hosted by the ACS. The ACS uses JavaScript on this webpage to collect info about the customer’s browser.

When the ACS has finished collecting the browser info, it will make a POST request from the iframe to your Method Notification URL.

The handler for your Method Notification URL must be prepared to receive a request in the following format:

POST https://example-merchant.com/3ds/method-notification HTTP/1.1
Host: api.example-merchant.com
Content-Type: application/x-www-form-urlencoded

threeDSMethodData=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSJ9

The threeDSMethodData field contains a base64 encoded JSON string containing the threeDSServerTransID in the following format:

{
    "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149"
}

Your back-end must decode this request and record that the Method Request was successful for the specified threeDSServerTransID and when sending the Authenticate Request set the areqData.threeDSCompInd field to Y.

If the Method Request was not completed successfully within 10 seconds you should set the areqData.threeDSCompInd field to N.

You may simply respond to the call to your Method Notification URL with an HTTP 200. The 3DS JavaScript will delete the iframe when it receives a response from your Method Notification URL.

If you were executing the Version and Method Requests synchronously after the customer submitted their order, you must immediately make another request from your front-end to your back-end to initiate the Authenticate Request. This can be done by adding a JavaScript message event listener, which checks for messages received from your Method Notification URL.

If you were executing these requests asynchronously, wait until the customer submits their order to initiate the Authenticate Request.

Authenticate Request

To prepare an Authenticate Request your back-end must gather the required customer and transaction data.

See our 3D Secure API reference for full details of the Authenticate Request.

The messageVersion field is optional and will default to the versionRecommendation returned in the Version Response.

Ensure you send all the required fields, and as many optional fields as you can. The more optional fields you provide, the greater the chance of the transaction achieving a Frictionless authentication.

The Ravelin 3DS Server proceeds with the 3D Secure process. The authentication request is sent to the ACS which decides whether a challenge is required.

The Authenticate Response will be returned to your back-end.

An example of a successful Authenticate Response is shown below:

{
  "status": 200,
  "timestamp": 1600081748,
  "cardScheme": "Visa",
  "data": {
    "messageVersion": "2.2.0",
    "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
    "acsTransID": "161d6b82-0d47-4e4b-b617-20cf6ba75754",
    "dsTransID": "7f2774c2-3b6b-43b3-b121-5179f64075b2",
    "acsReferenceNumber": "example-acs-reference-number",
    "dsReferenceNumber": "example-ds-reference-number",
    "transStatus": "Y",
    "eci": "05",
    "authenticationValue": "bG9va2l0c2FuZWFzdGVyZWdnIQo="
  }
}

An example of an Authenticate Response which requires a challenge is shown below:

{
  "status": 200,
  "timestamp": 1600081748,
  "data": {
    "messageVersion": "2.2.0",
    "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
    "acsTransID": "161d6b82-0d47-4e4b-b617-20cf6ba75754",
    "dsTransID": "7f2774c2-3b6b-43b3-b121-5179f64075b2",
    "acsReferenceNumber": "example-acs-reference-number",
    "dsReferenceNumber": "example-ds-reference-number",
    "transStatus": "C",
    "acsURL": "https://example-acs.com/challenge",
    "acsChallengeMandated": "N",
    "authenticationType": "01"
  }
}

See our 3D Secure API reference for full details of the Authenticate Response.

The Authenticate Response transStatus field describes the next action you need to take.

Challenge Request

Using the Authenticate Response you must prepare a Challenge Request (CReq).

Your back-end should respond to your front-end with the messageVersion, threeDSServerTransID, acsTransID, and acsURL values. Your front-end should then select the appropriate challengeWindowSize and prepare the Challenge Request.

An example Challenge Request is shown below:

{
  "messageType": "CReq",
  "messageVersion": "2.2.0",
  "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
  "acsTransID": "161d6b82-0d47-4e4b-b617-20cf6ba75754",
  "challengeWindowSize": "01"
}

See our 3D Secure API reference for full details of the Challenge Request.

In order to support the Challenge Request your back-end needs an endpoint which can receive a notification when the challenge has finished. This endpoint is referred to as the Challenge Notification URL.

Your front-end must then call the SendChallengeRequest(acsURL, creq, sessionData, windowWidth, windowHeight) function, provided by the 3DS JavaScript, to send the Challenge Request to the ACS.

Session Data

You can optionally also provide session data in the sessionData argument. The session data will be returned in the Challenge Response, allowing you to associate Challenge Response with the corresponding Challenge Request. It is recommended that you populate the sessionData with your transactionId.

Displaying the Challenge Form

The 3DS JavaScript will create an iframe visible to the customer. From inside the iframe the CReq will be sent via a POST request to the acsURL.

The iframe will then display the challenge form to the customer. The cardholder will enter their authentication data (for example, a one time password sent to them via SMS) into the challenge form.

When the cardholder submits the challenge form, their authentication data will be sent to the ACS.

The ACS will evaluate the authentication data to determine whether the customer successfully authenticated themselves.

Once the challenge has completed, the ACS will make a POST request from the iframe to your Challenge Notification URL.

You must provide your Challenge Notification URL in the areqData.notificationURL field of the Authenticate Request.

The handler for your Challenge Notification URL should be prepared to receive a request in the following format:

POST https://example-merchant.com/3ds/challenge-notification HTTP/1.1
Host: api.example-merchant.com
Content-Type: application/x-www-form-urlencoded

threeDSSessionData=ewogICAgInRyYW5zYWN0aW9uSWQiOiAiMTIzLWFiYy1YWVoiCn0&
cres=ewogICAgIm1lc3NhZ2VUeXBlIjogIkNSZXMiLAogICAgIm1lc3NhZ2VWZXJzaW9uIjogIjIuMi4wIiwKICAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ICJiZmM0NGNhNy0wMzczLTQyM2UtOGY1NS1lNTdlNjUyM2ExNDkiLAogICAgInNka1RyYW5zSUQiOiAiNTQ2MGMzYWItMjY3NC00ZmEwLWIwOTgtZjdjZGY0MGRlNWI5IiwKICAgICJhY3NUcmFuc0lEIjogIjE2MWQ2YjgyLTBkNDctNGU0Yi1iNjE3LTIwY2Y2YmE3NTc1NCIsCiAgICAidHJhbnNTdGF0dXMiOiAiTiIsCiAgICAiY2hhbGxlbmdlQ29tcGxldGlvbkluZCI6ICJZIiwKICAgICJhY3NDb3VudGVyQXRvUyI6ICIwMDEiCn0K

The threeDSSessionData field contains a base64 encoded JSON string containing the threeDSSessionData which you provided to the SendChallengeRequest function.

The cres field contains a base64 encoded JSON string containing the Challenge Response. An example, decoded Challenge Response is shown below:

{
  "messageType": "CRes",
  "messageVersion": "2.2.0",
  "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
  "acsTransID": "161d6b82-0d47-4e4b-b617-20cf6ba75754",
  "transStatus": "Y"
}

See our 3D Secure API reference for full details of the Challenge Response.

Your back-end must base64 decode the Challenge Response (cres) value.

The Challenge Response transStatus field describes the next action you need to take.

For all transStatus values, see the transStatusReason field for more detail.

Result Request

If the transaction status in the Challenge Response was Y, your back-end must send a Result Request to obtain the Authentication Value. The Authentication Value is used to authorise the transaction with your payment gateway.

If you are interested in why a challenge was unsuccessful, your back-end can still call the Result Request endpoint to receive the transStatusReason.

The handler for your Challenge Notification URL may make the Result Request, or a new request from your front end to your back-end can initiate the Result Request.

If sending a new request, a JavaScript message event listener, which checks for messages received from your Challenge Notification URL, can be created on your front-end in order to initiate the Result Request.

An example Result Request is shown below:

POST https://3ds.live.pci.ravelin.com/3ds/result HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149"
}

See our 3D Secure API reference for full details of the Result Request.

If the authentication was successful, the response will contain the Authentication Value.

An example successful Result Response is shown below:

{
  "status": 200,
  "timestamp": 1600081748,
  "cardScheme": "Visa",
  "data": {
    "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
    "messageVersion": "2.2.0",
    "transStatus": "Y",
    "eci": "05",
    "authenticationValue": "dGVzdHltY3Rlc3QsaGV5dGhlcmUK"
  }
}

See our 3D Secure API reference for full details of the Result Response.

The Result Response transStatus field describes the next action you need to take.

Updating the Front-End

The handler for your Challenge Notification URL can respond with HTML which contains JavaScript to post a message to the parent window.

<script type="text/javascript">
    window.parent.postMessage({ status: "COMPLETE" }, "*");
</script>

An event listener on the parent window can listen for this message and update the page accordingly.

window.addEventListener('message', (e) => {
    if (e.origin === window.location.origin) {
        if (e.data.hasOwnProperty('status')) {
            document.getElementById('challengeIframe').remove();
        }
    }
});

This completes the 3D Secure Browser Flow.

Next steps

Test your 3DS integration with our test cards

Integrate 3D Secure into your mobile app

Feedback

Was this page helpful?

Thanks for the feedback. If you'd like to provide more detail, please email support@ravelin.com.