3DS Browser Integration Guide

This guide explains how to use Ravelin’s 3DS Server to perform 3D Secure authentication in a browser.

Steps

Browser Flow Diagram

The 3D Secure browser flow is shown below:

%%{ init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#ececff' } } }%% sequenceDiagram participant FRONTEND as Client Front-End participant BACKEND as Client Back-End participant 3DS_SERVER as Ravelin 3D Secure participant ACS as Issuer ACS FRONTEND ->> BACKEND: PAN & Browser Info BACKEND ->> 3DS_SERVER: Version Request 3DS_SERVER ->> BACKEND: Version Response BACKEND ->> FRONTEND: Method Details FRONTEND ->> ACS: Method Request ACS ->> BACKEND: Method Notification FRONTEND ->> BACKEND: Start Authentication BACKEND ->> 3DS_SERVER: Authenticate Request 3DS_SERVER ->> BACKEND: Authenticate Response FRONTEND --> ACS: If a challenge is required BACKEND ->> FRONTEND: Challenge Details FRONTEND ->> ACS: Challenge Request ACS ->> BACKEND: Challenge Notification BACKEND ->> 3DS_SERVER: Result Request 3DS_SERVER ->> BACKEND: Result Response

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 the 3D Secure protocol version which the customer’s card 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:

{
    "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,
    "data": {
        "transactionId": "123-abc-XYZ",
        "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
        "availableVersions": ["1.0.2", "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 this value 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.

If the card does not support 3D Secure 2, the response will be:

{
    "status": 200,
    "timestamp": 1600081748,
    "data": {
        "transactionId": "123-abc-XYZ",
        "availableVersions": ["1.0.2"],
        "versionRecommendation": "1.0.2"
    }
}

In this case, you should follow our 3DS 1 Integration Guide (coming soon).


Method Request

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

This request can be performed as soon as the threeDSMethodURL and threeDSServerTransID from the Version Response have been 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 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 you 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.

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,
    "data": {
        "threeDSServerTransID": "bfc44ca7-0373-423e-8f55-e57e6523a149",
        "acsTransID": "161d6b82-0d47-4e4b-b617-20cf6ba75754",
        "messageVersion": "2.2.0",
        "transStatus": "Y",
        "eci": "05",
        "authenticationValue": "bG9va2l0c2FuZWFzdGVyZWdnIQo="
    }
}

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.

Transaction Status Description Next Action
Y Authentication Successful The transaction achieved a Frictionless authentication, continue to authorisation using the authenticationValue from the Authenticate Response.
A Authentication Attempted 3DS was attempted but was not possible. However the card scheme granted a successful authentication on the issuer’s behalf.
N Authentication Failed The authentication failed, stop processing the transaction.
U Authentication Unavailable Authentication could not be performed. You may attempt to proceed to authorisation without an authenticationValue.
R Authentication Rejected The issuer rejected the authentication attempt and requests that authorisation is not attempted.
C Challenge Required A challenge is required, make a Challenge Request.
D Decoupled Challenge Required Decoupled authentication will be performed by the issuer. Make a Result Request to learn the final outcome.
I Informational Only Authentication for the transaction was not requested. The data was sent to the ACS for informational purposes only.

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


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, threeDSSessionData) 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 threeDSSessionData 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 threeDSSessionData 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",
    "acsCounterAtoS": "001"
}

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

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

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

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

Transaction Status Description Next Action
Y Authentication successful The challenge was successful, make a Result Request to obtain the authentication value.
N Authentication failed The authentication failed, stop processing the transaction.

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.

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:

{
    "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,
    "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.

Transaction Status Description Next Action
Y Authentication Successful The authentication was successful, continue to authorisation using the authenticationValue from the Result Response.
A Authentication Attempted 3DS was attempted but was not possible. However the card scheme granted a successful authentication on the issuer’s behalf.
N Authentication Failed The authentication failed, stop processing the transaction.
U Authentication Unavailable Authentication could not be performed. You may attempt to proceed to authorisation without an authenticationValue.
R Authentication Rejected The issuer rejected the authentication attempt and requests that authorisation is not attempted.

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

This completes the 3D Secure Browser Flow.