3DS 1 Integration Guide

This guide explains how to perform authentication with 3DS 1.

The 3DS 1 authentication process is similar to the 3DS 2 browser flow when a challenge is required.

Steps

3DS 1 Flow Diagram

The 3D Secure 1 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: Version Details FRONTEND ->> BACKEND: Start Authentication BACKEND ->> 3DS_SERVER: Authenticate Request 3DS_SERVER ->> BACKEND: Authenticate Response BACKEND ->> FRONTEND: Challenge Details FRONTEND ->> ACS: Challenge Request ACS ->> BACKEND: Challenge Notification BACKEND ->> 3DS_SERVER: Result Request 3DS_SERVER ->> BACKEND: Result Response

Version Request

The Version Request determines whether the customer’s card supports 3DS 2.

The Version Request for 3DS 1 is the same as 3DS 2.

To prepare for this request your front-end must send the customer’s primary account number (PAN) to your back-end. 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.

Your back-end must 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.

If the card does not support 3DS 2 the Version Response will recommend that you use 3DS 1. However, this does not mean that the card actually supports 3DS 1, in order to determine whether the card supports 3DS 1 you must make an Authenticate Request.

An example Version Response, when the payment card does not support 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"],
        "versionRecommendation": "1.0.2"
    }
}

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


Authenticate Request

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

Ensure you send all the 3DS 1 required fields.

An example of a 3DS 1 Authenticate Request is shown below:

{
    "timestamp": 1634304030,
    "customerId": "123-abc-XYZ",
    "transactionId": "123-abc-XYZ",
    "areqData": {
        "messageVersion": "1.0.2",
        "purchaseAmount": "10000",
        "purchaseCurrency": "826",
        "purchaseExponent": "2",
        "pan": "4100000000000002",
        "cardExpiryDate": "2201",
        "threeDSRequestorURL": "https://www.example-requestor.com",
        "acquirerMerchantID": "01234",
        "acquirerBIN": "999999",
        "merchantName": "Example Merchant",
        "merchantCountryCode": "826",
        "browserAcceptHeader": "text/html,application/xml",
        "browserUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_0_0) AppleWebKit/0.0 (KHTML, like Gecko) Chrome/0.0.0.0 Safari/0.0",
    }
}

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

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

An example 3DS 1 Authenticate Response is shown below:

{
    "status": 200,
    "timestamp": 1634304030,
    "data": {
        "messageVersion": "1.0.2",
        "threeDSServerTransID": "236e9d43-64a4-45b4-b76f-24ef521660e5",
        "acsURL": "https://pci-acs-staging.ravelin.com/acs/3ds1/pareq",
        "paReq": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhHQ00iLCJraWQiOiI2NWUzODBkYi1mZDRiLTQwZTMtOWI4NS1hZTY2N2JhYzkzZjMifQ.m_c8EvDR6MWFTwoRtgV3yi_ZnPax91zZhPwdI6m4fO3XYNPFcwGkHFUYnEezhGMgILpzlCkn5IqYnFbrtBMV6ewD638EtinsfjrA02mvGDZNSVjZ23aOx2RjXDo8-k-I_kqk8NDrDVpNyDHLkgY0Npd42yUsJHUy0FXz-U3m6EWdqfcO4SIWLsa3yL5L3ptkQFfuYGKumrJVcqAjEr3KV3QNpPGTiHvbzHjFvuxXQaZdgvwoEWg-FXOm_MYr1Skvd3Am5_se6Ml3t6YlOW0elH9czaDEGv9foyVJ-Wt5Y0mPeW2MBRhIXORLMEupIP4wz-UWbuNZSezoxvcios2_PQ.t45lXx91qMBJO8o1.-AgE7WNJ2Qtkhb00L044Psbljz8o0NxKZHM_E34n2M8IbjsGz6LgSRAiemLQoLklvOPn8ZfcTUIqvv_l42-20EYSdFvBGZXk5QUsV49I621vxLcrvXcFfOuyGa-gDjfnEg9LipNn27aXlxsAfWUWWLUR9PvQB2MZkLAei1i14KGBeCexuP6tY9wHptAVmU1d-M2DwdXQ3SPJSyb6c-zspsyOPGe-cy8BciKiVtBbVUrtNHEkRKspQZsoNJpiIPN-NyLGZq6f5JQXyiL5O6YTkPs6lJLM6exmQ2JoKUC51IAu8PV7CFCLdFHOf9nxn1OxmqFlzV-ajs3AppPPZZVWogW17CujB0b1sGJHUX6na2siKa1_lQTbTpX0MoqdNcKx2wB14Z3s7bZHx3f9ET5UPyZwh-ruF4sfbOaWSBh-M3i3hr51Mg2gHVQ7V_vV8sIhJ3s9i8xAwe-xLjYDx_mx297Qx6cEnGLpxCFqBIN4BCl14PugNLuaUzIk-UNyeuB2LOnQsQY5mBlKxKAWPpKTWfXRkj5hbF4arqezx6pPuZH1_X0fKyIKfJL0OHoMCPr0hplT5pXvNgb3x-yGmoG3CzP6OT_qaAcdbgqMrHhaXu0Us8B_dfRDha_-cWp1I_SPRipI6SFyE0F8iJGMk3X_2NInylVFyPOyouhIf7l8IlaINEpSHcASvtcGmHYMierfdXQ.yEimn7ry3ore6CyBhrgtxg"
    }
}

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

Your back-end should respond to your front-end with the acsURL and paReq values from the Authenticate Response. These are required to perform the challenge.


Challenge Request

All 3DS 1 authentications require a challenge.

In order to support the 3DS 1 challenge your back-end needs an endpoint which can receive a notification when the challenge has finished. This endpoint is referred to as the Term URL.

Your front-end must call the Send3DS1ChallengeRequest(acsUrl, paReq, md, termURL, windowWidth, windowHeight) function, provided by the 3DS JavaScript, to initiate the challenge with the ACS.

Merchant Data

You can optionally provide merchant data in the md argument. This will be returned with the Payer Authentication Response (PARes), allowing you to associate the PARes with the corresponding PAReq. It is recommended that you populate md with your transactionId.

Displaying the Challenge Form

The 3DS JavaScript will create an iframe visible to the customer. From inside the iframe the PAReq 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 Term URL.

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

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

MD=123-abc-XYZ&
PaRes=eJycVNty2jAQ/RWGPHaMJF+wnVk0wy0JJLQJpFzyJuyNcceWqS0HyNd3ZK5N89BWL9492j3n6GLB8ypH7E0wKHPkMMKiEBHW4rBVDzw3NJshMwSjnmGbljC8pi8M59VeOqFne0vq1jk8tsdY/EvDG+ZFnEnOGrRhAjmmMMI8WAmpOIjgZ2fwldNq+L4P5IBAivmgx33PbTq2ZTJKKQOyB0GKFHl/K9J1gjWrN6kdCYFUU9DNSqnyHffMJpBjAuSs+1jqqEAO2zjkT7PO/ePdze6JsZtv0yGdd4fzyW1nPt4tgOgCCIVCblKTMcqcGnOvmXttOkAqHESqJbinFwHkkMFaa7R/m7qEICjzHGVwcHnKALfrTKJU3ARyioGcLa+FPOzYeQDRKDzPOag4/cOr5QOpcCiUUGXBF0AOEQTi7Y0/TIerMJ0WYmZH09vpe9jtzBazLXuZ0BaQqgQwiDl1gOhv1dVOoiyP1Srl7r7mDADRVkh1ZThM4kgKVeZY26aJLFr1lVLra0I2m01jYzWyPCImpZRQn2zTJCzi6Kq+78JwIF8zDl0hMxkHIonfhYozOUK1ysLaSfAzyuexZmVk3O8a2zQxAmZLQyPUYk6dA/mc9MLu36h8NJ4XwihWgmmBD0QcxviK+pix9n08aNWvrDBwbWELY+l6lmEz0zH8oOkYHtqhF6DrWU3ttBdHWKj/cXN0cslw5JuKpEQ+ypb2zfBHefeCc3xKH+5e2v1lf7lIvkStY9++EsjJ/mFtx9O5x90+mDvU7wklOJCL8DR93pDqb6xeIH1VLl+mXwEAAP//QECBVQ==

The MD field contains the Merchant Data (md) which you provided to the Send3DS1ChallengeRequest function.

The PaRes field contains the Payer Authentication Response in a base64 encoded XML format.

Your back-end must send the PARes to Ravelin in a Result Request.


Result Request

The handler for your Term URL must make the Result Request to learn the outcome of the challenge.

An example Result Request is shown below:

{
    "paRes": "eJycVNty2jAQ/RWGPHaMJF+wnVk0wy0JJLQJpFzyJuyNcceWqS0HyNd3ZK5N89BWL9492j3n6GLB8ypH7E0wKHPkMMKiEBHW4rBVDzw3NJshMwSjnmGbljC8pi8M59VeOqFne0vq1jk8tsdY/EvDG+ZFnEnOGrRhAjmmMMI8WAmpOIjgZ2fwldNq+L4P5IBAivmgx33PbTq2ZTJKKQOyB0GKFHl/K9J1gjWrN6kdCYFUU9DNSqnyHffMJpBjAuSs+1jqqEAO2zjkT7PO/ePdze6JsZtv0yGdd4fzyW1nPt4tgOgCCIVCblKTMcqcGnOvmXttOkAqHESqJbinFwHkkMFaa7R/m7qEICjzHGVwcHnKALfrTKJU3ARyioGcLa+FPOzYeQDRKDzPOag4/cOr5QOpcCiUUGXBF0AOEQTi7Y0/TIerMJ0WYmZH09vpe9jtzBazLXuZ0BaQqgQwiDl1gOhv1dVOoiyP1Srl7r7mDADRVkh1ZThM4kgKVeZY26aJLFr1lVLra0I2m01jYzWyPCImpZRQn2zTJCzi6Kq+78JwIF8zDl0hMxkHIonfhYozOUK1ysLaSfAzyuexZmVk3O8a2zQxAmZLQyPUYk6dA/mc9MLu36h8NJ4XwihWgmmBD0QcxviK+pix9n08aNWvrDBwbWELY+l6lmEz0zH8oOkYHtqhF6DrWU3ttBdHWKj/cXN0cslw5JuKpEQ+ypb2zfBHefeCc3xKH+5e2v1lf7lIvkStY9++EsjJ/mFtx9O5x90+mDvU7wklOJCL8DR93pDqb6xeIH1VLl+mXwEAAP//QECBVQ=="
}

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

If the authentication was successful, the Result Response will contain the Authentication Value.

An example successful Result Response is shown below:

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

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

The Result Response transStatus field describes the outcome of the authentication.

Transaction Status Description Next Action
Y Authentication Successful Continue to authorisation using the authenticationValue from the Result Response.
A Authentication Attempted The cardholder was not authenticated, but proof of the authentication being attempted has been provided. Continue to authorisation using the authenticationValue from the Result Response.
N Authentication Failed Only proceed to authorisation if authentication is not required, and this is within your risk appetite.
U Authentication Unavailable Only proceed to authorisation if authentication is not required, and this is within your risk appetite.

Updating the Front-End

The handler for your Term 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 3DS 1 Flow.