Skip to content

Non-hosted sessions

Last updated: July 20, 2022

For full control over your 3D Secure authentication flow, use non-hosted sessions. These will be initiated by your backend.

Non-hosted sessions are suitable for authentications initiated for both browsers and mobile apps.


Authenticating your requests

Access tokens

All Sessions API endpoints will accept a valid JSON web token (JWT) bearer token. These short-lived tokens can be generated using your client id and secret, which you will have received when you created your account.

Tokens must contain the scope sessions:browser for browser channel flows or sessions:app for native mobile app channel flows. If you are unsure of the channel you're going to use when you request the session, you can include both scopes.

Session secret

All endpoints following the request to create a new session will also accept the session secret; creating a session will return a session_secret property, which can be used in the Authorization header of subsequent requests for that session.

The session_secret is short-lived randomly generated string that can only be used for actions taken on a specific session, reducing the chance of it being leaked. This way the frontend does not have to have access to the client secrets required to create JWT tokens (which, if exposed to the frontend, can risk being leaked to malicious third parties).

Note that any endpoint accessible with session_secret can also be accessed with a valid JWT token. This can be useful if you intend to access the endpoints from your backend, for instance, because you proxy the requests instead of making them directly from the frontend.


Step 1: Request a session

This is the first step to starting a 3DS authentication flow with Sessions. Authenticate the call with an access token and perform it from your backend.

Endpoints

For the full API specification, see the API reference.

    post

    https://api.checkout.com/sessions

    Copied!

    Additional parameters

    To increase the likelihood of frictionless authentication, add additional data fields when requesting a session.

    Channel data

    If you create a session with channel data, there is no need to update the channel data later on. A javascript_enabled field is required in the channel data to use 3DS version 2.2.0. See step 4 for more information.

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    {
    "source": {
    "type": "card",
    "number": "4485040371536584",
    "expiry_month": 1,
    "expiry_year": 2030
    },
    "amount": 100,
    "currency": "USD",
    "authentication_type": "regular",
    "authentication_category": "payment",
    "challenge_indicator": "no_preference",
    "reference": "ORD-5023-4E89",
    "transaction_type": "goods_service",
    "shipping_address": {
    "address_line1": "Checkout.com",
    "address_line2": "90 Tottenham Court Road",
    "city": "London",
    "state": "UK",
    "zip": "W1T 4TJ",
    "country": "GB"
    },
    "completion": {
    "type": "non_hosted",
    "callback_url": "https://example.com/sessions/callback"
    }
    }

    Response example

    You should receive a 202 - Accepted response, with a status of pending. It will also contain:

    • The session id (prefixed by sid_), which you'll use to get the session details in the next step.

    • A _links.three_ds_method_url URL, where the cardholder should be redirected to complete the Issuer Fingerprint, if the card supports this feature.

    • A next_actions property, which will tell you what action(s) to take next.

    With the introduction of 3DS version 2.2.0, you may receive a 2.2.0 value in the protocol_version field in the response.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    {
    "session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=",
    "id": "sid_llraltf4jlwu5dxdtprcv7ba5i",
    "transaction_id": "cc05e25a-4abc-4eed-8ee3-9be22afc20ea",
    "amount": 6540,
    "currency": "USD",
    "completed": false,
    "authentication_type": "regular",
    "authentication_category": "payment",
    "status": "pending",
    "approved": false,
    "protocol_version": "2.1.0",
    "reference": "ORD-5023-4E89",
    "next_actions": [
    "collect_channel_data",
    "issuer_fingerprint"
    ],
    "transaction_type": "goods_service",
    "_links": {
    "self": {
    "href": "https://3ds2.ckotech.co/sessions/sid_llraltf4jlwu5dxdtprcv7ba5i"
    },
    "three_ds_method_url": {
    "href": "https://api.hbsc.com/3dsmethod?tx=123456"
    }
    }
    }

    Exemptions

    To increase the likelihood of a frictionless transaction, request an exemption in your API request. You can request an exemption for transactions that must be Strong Customer Authentication (SCA) compliant, provided it meets the listed possible exemptions.

    You are able to submit exemptions directly in the authorization stage of the payment flow if that is your preference.

    Exemptions are only supported by Visa and Mastercard. Exemptions requested by you may change based on what’s supported by the scheme.

    Liability shift

    If you request an exemption, and the customer’s bank approves it, you do not benefit from the liability shift. This means you would be liable if the transaction turned out to be fraudulent.

    You will need to opt in to use exemptions. Transaction Risk Assessment (TRA) is only applicable to merchants with low fraud rate. Contact your Customer Success Manager to enable this feature.

    ExemptionDescription

    low_value

    For payments where the amount does not exceed €30.

    SCA may still be requested by the issuer despite the payment satisfying the requirements for low_value exemption. This may be due to either:

    • The cumulative amount for transactions initiated by the cardholder since the last SCA authentication exceeds €100.
    • The consecutive number of payment transactions initiated by the cardholder since the last SCA authentication exceeds 5.

    secure_corporate_payment

    For payments that use secure corporate cards, which are exempt from 3D Secure authentication.

    trusted_listing

    For payments where the cardholder has already added the merchant as a trusted merchant.

    trusted_listing_prompt

    For payments where the merchant would like to bring up a prompt to allow the cardholder to add the merchant as a trusted merchant.

    This will request for a challenge, which will have a prompt to allow the cardholder to add the merchant as a trusted merchant.

    transaction_risk_assessment

    For payments that satisfy the authentication amount criteria set by Checkout.com.

    • €100 to €250 for Checkout.com UK acquirer
    • €250 to €500 for Checkout.com FR acquirer

    If the issuer rejects the exemption, they will request a challenge, which the cardholder is required to complete

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    {
    "source": {
    "type": "card",
    "number": "4485040371536584",
    "expiry_month": 1,
    "expiry_year": 2030
    },
    "amount": 100,
    "currency": "USD",
    "authentication_type": "regular",
    "authentication_category": "payment",
    "challenge_indicator": "low_value",
    "reference": "ORD-5023-4E89",
    "transaction_type": "goods_service",
    "shipping_address": {
    "address_line1": "Checkout.com",
    "address_line2": "90 Tottenham Court Road",
    "city": "London",
    "state": "UK",
    "zip": "W1T 4TJ",
    "country": "GB"
    },
    "completion": {
    "type": "non_hosted",
    "callback_url": "https://example.com/sessions/callback"
    }
    }

    Recurring and installment payments

    In regions where SCA is mandated, following the Payment Services Directive (PSD2) means the initial cardholder-initiated transaction (CIT) payment will require SCA. As such, you must authenticate the CIT with a challenge in these mandated regions.

    In your API request, set authentication_type to recurring or installment.

    You will also need to send the recurring or installment object with the following required fields.

    Visa requirements

    For Visa payments, the initial customer-initiated transaction (CIT) to set up a recurring or installment series should be processed as a regular authentication and the additional fields described in the following fields are not required.

    number_of_payments

    Only applies to installment payments.

    Integer
    Min : 1
    Indicates the agreed total number of payment installments to be made in the duration of the installment agreement.

    days_between_payments

    Integer
    Default : 1
    Indicates the minimum number of days between authorisations. If no value is specified for a recurring authentication type the default value will be used.

    expiry

    String
    Default : "99991231"
    Date after which no further authorisations are performed in the format YYYY/MM/DD. If no value is specified for a recurring authentication type the default value will be used.

    For non-recurring or non-installment payments, these fields will be ignored if they are sent to the API.

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    {
    "source": {
    "type": "card",
    "number": "4485040371536584",
    "expiry_month": 1,
    "expiry_year": 2030
    },
    "amount": 100,
    "currency": "USD",
    "authentication_type": "installment",
    "installment": {
    "number_of_payments": 12,
    "days_between payments": 28,
    "expiry": 20251231
    },
    "authentication_category": "payment",
    "reference": "ORD-5023-4E89",
    "transaction_type": "goods_service",
    "shipping_address": {
    "address_line1": "Checkout.com",
    "address_line2": "90 Tottenham Court Road",
    "city": "London",
    "state": "UK",
    "zip": "W1T 4TJ",
    "country": "GB"
    },
    "completion": {
    "type": "non_hosted",
    "callback_url": "https://example.com/sessions/callback"
    }
    }

    Step 2: Get session details

    Next, you need to gather the device data (meaning the details of the browser or mobile app that initiated the session) in order to make an authentication request. To do so, get the current session details with the following request.

    You can skip this step if your backend forwards the response of requesting a new session to your frontend.

    Endpoints

    For the full API specification, see the API reference.

      get

      https://api.checkout.com/sessions/{session_id}

      Copied!

      Response

      You will get a response with the property next_actions, which will tell you what you need to do next.

      Field nameDescription

      id

      string

      The unique identifier of the session.

      next_actions

      array

      Specifies what action to take to complete the session. Will be one of: collect_channel_data, issuer_fingerprint (browser-initiated only), challenge_cardholder, or complete.

      status

      string

      The status of the session. Should be pending.


      Step 3: Issuer fingerprint (browser only)

      If there is no three_ds_method_url property available in the response, Sessions will automatically set the three_ds_method_completion property to U and continue the flow. You do not have to make a POST request to the Issuer Fingerprint endpoint. The following actions will be collect_channel_data, challenge_cardholder or complete, with their corresponding status pending, challenged or one of approved, declined, rejected or expired.

      If one of the next actions after creating the session was issuer_fingerprint, this step must be completed before proceeding with the session.

      This involves the customer's browser contacting the Access Control Server directly so that the latter can calculate a fingerprint of it.

      a) Create payload

      To do this, you first need to construct the following payload:

      1
      2
      3
      4
      {
      "threeDSServerTransID": //the transaction_id property of the session,
      "threeDSMethodNotificationURL": //the URL that will receive the 3DS method notification message
      }

      This payload needs to be base64 encoded and sent to the three_ds_method_url property of the _links object of the session using a POST request and putting the base64 encoded data in a form field called threeDSMethodData.

      b) Redirect

      This will trigger a POST redirect to the threeDSMethodNotificationURL with a form parameter named threeDSMethodData. This will be a base64 encoded payload that, when decoded, will look like the following:

      1
      2
      3
      {
      "threeDSServerTransID": //the transaction_id property of the session
      }

      If you do not wish to handle the notification manually you can use our interceptor application to do it for you. To do so, set the threeDSMethodNotificationURL with the applicable endpoint:

        post

        https://api.checkout.com/sessions-interceptor/3ds-method-notification

        Copied!

        c) Notification of completion

        After you POST the threeDSMethodData, you can be notified about the completion by listening for a browser event as follows:

        1
        window.addEventListener("message", messageCallback, false);

        Where messageCallback is a function with the following signature:

        1
        2
        3
        function messageCallback(event){
        console.log(event.data)
        }

        And event.data will contain the following object:

        1
        2
        3
        {
        “threeDSServerTransID”: //the transaction_id property of the session
        }

        d) Fingerprint completed

        In order to update the three_ds_method_completion property, you'll need to send a POST request to the issuer_fingerprint property of the _links object of the session.

        Once you've received the message, the fingerprint has completed successfully and you can set the three_ds_method_completion property to Y.

        If you don't receive the message within 10 seconds of initiating the flow, set this property to N. You will need to implement a timeout logic to account for this.

        The response you receive from the Notification of Completion will only contain threeDSServerTransID and not a value of Y/N/U. The three_ds_method_completion property is determined only by which route the Issuer Fingerprint step takes.

        Alternatively, if the session was created without channel data and you need to submit this after the Issuer Fingerprint step, you can make a single POST request to /sessions/{id}/collect-data (see Step 4) with the three_ds_method_completion property in the payload. This means you don't need to make a separate PUT request to /sessions/{id}/issuer-fingerprint.


        Step 4: Collect channel data

        Once you've completed the relevant actions indicated by the next_actions property, you need to update the session with the collected device data to make the authentication request.

        A javascript_enabled field is introduced in the channel data for 3DS version 2.2.0. If this field is not provided in the request, we will add it and default the value to true.

        If you created the session with channel data, there is no need to complete this step. This step will be handled by our mobile SDKs for mobile app flows.

        Endpoints

        For the full API specification, see the API reference.

          put

          https://api.checkout.com/sessions/{session_id}/collect-data

          Copied!

          Body parameters

            Field nameDescription

            channel

            required
            string

            Indicates the interface (either browser or app) being used to initiate the transaction. Set this to browser.

            accept_header

            required
            string

            Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser.

            java_enabled

            required
            boolean

            Boolean that represents the ability of the cardholder browser to execute Java. The value is returned from the navigator.javaEnabled property.

            javascript_enabled

            optional
            boolean

            Boolean that represents the ability of the cardholder browser to execute JavaScript.

            Default: true

            language

            required
            string

            Value representing the browser language as defined in IETF BCP47. Returned from the navigator.language property.

            color_depth

            required
            string

            Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from the cardholder's browser using the screen.colorDepth property.

            screen_height

            required
            string

            Total height of the cardholder’s screen in pixels. Value is returned from the screen.height property.

            screen_width

            required
            string

            Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.

            timezone

            required
            string

            Time difference between UTC time and the local time of the cardholder's browser, in minutes.

            user_agent

            required
            string

            Exact content of the HTTP user-agent header.

            ip_address

            required
            string

            IP address of the browser as returned by the HTTP headers to the 3DS Requestor.

            three_ds_method_completion

            optional
            string

            Indicates whether the 3DS Method successfully completed.

            • Y: successfully completed
            • N: did not successfully complete
            • U: Unavailable (3DS Method URL was not present in the preparation response message data for the card range associated with the cardholder's account number).

            Response example

            Once the update is received, an authentication request will be sent, returning an authentication response from the issuer with the outcome of the authentication: approved, attempted, unavailable, declined, rejected, or challenged.

            This outcome sets the next_actions property in the update response, letting you know what to do next.

            If an exemption was sent in the request and was successfully applied, you should expect an exemption object in the response.

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            {
            "exemption": {
            "requested": "transaction_risk_assessment",
            "applied": "transaction_risk_assessment",
            "trusted_beneficiary": {
            "status": "Y",
            "source": "ACS"
            }
            }
            }

            Additional response fields

            Field nameDescription

            id

            string

            The unique identifier of the session.

            next_actions

            array

            Specifies what action to take to complete the session.

            • challenge_cardholder: the issuer is challenging the authentication and the cardholder will need to submit additional credentials.

            • complete: no further actions need to be taken. You can complete the session.

            status

            string

            The status of the session. Should be processing. If expired, the authentication was started but could not be completed.


            Step 5 a: 3DS2 (browser only)

            This is only relevant for browser-based authentications. Our mobile SDKs will handle the challenge flow for mobile app authentications.

            If, after completing the issuer fingerprint and channel data steps, the authentication is approved/declined immediately—the "frictionless" flow—you can proceed to complete the session.

            If not, the cardholder will now be challenged to provide additional information to authenticate the payment—the "challenge" flow.

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13
            14
            15
            16
            17
            18
            19
            20
            21
            22
            23
            24
            25
            26
            27
            28
            29
            30
            31
            32
            33
            34
            35
            {
            "id": "sid_r5supjqo6kduppai4u56apandi",
            "transaction_id": "a647658f-f20e-4787-bc08-e53be03c0d1a",
            "amount": 1000,
            "currency": "GBP",
            "completed": false,
            "authentication_type": "regular",
            "authentication_category": "payment",
            "status": "challenged",
            "protocol_version": "2.1.0",
            "next_actions": [
            "challenge_cardholder"
            ],
            "ds": {
            "reference_number": "0c6e7212-710a-48c6-9e67-bf889569",
            "transaction_id": "a05d24dd-b450-4d9c-9623-5df6835975f6"
            },
            "acs": {
            "reference_number": "6f66a1bd-c4e0-4d6d-b233-739b5a2d",
            "transaction_id": "d990b286-f75b-4347-9371-c66132cd7c21",
            "operator_id": "cf99f707-d05d-44ac-bd4d-af691f82",
            "url": "http://3ds2.ckotech.co/3ds2simulator/acs/challenge",
            "challenge_mandated": true,
            "authentication_type": "01"
            },
            "response_code": "C",
            "response_status_reason": "01",
            "challenged": true,
            "transaction_type": "goods_service",
            "_links": {
            "self": {
            "href": "https://3ds2-sandbox.cko.lon/sessions/sid_r5supjqo6kduppai4u56apandi"
            }
            }
            }

            Create challenge request

            The next_actions field will contain the challenge_cardholder action (see example above). To proceed, create the challenge request (CReq) message as follows:

            1
            2
            3
            4
            5
            6
            7
            {
            "threeDSServerTransID": //the transaction_id field of the session,
            "acsTransID": //the acs.transaction_id field of the session,
            "messageType":"CReq",
            "messageVersion": //the specific 3DS version used. Should be set to the protocol_version property of the session,
            "challengeWindowSize": //the requested challenge size. See below for possible values
            }
            Challenge window size valueSize

            01

            250-400px

            02

            390-400px

            03

            500-600px

            04

            600-400px

            05

            Full screen

            The style of the challenge window style is dependent on the issuer, so the above sizes may not be exact. We recommend that you render the challenge inside a frame so you have full control over the final size on your page.

            Once the CReq message is constructed, it must be base64 encoded and posted to the acs.url property of the session, in a form field named creq. Ensure that the encoded CReq message does not contain any padding.

            Render the challenge

            If the CReq message was successful, the response will be the HTML needed to render the challenge.

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13
            14
            15
            16
            17
            18
            19
            20
            21
            22
            23
            24
            25
            26
            27
            28
            29
            30
            31
            32
            33
            <!DOCTYPE html>
            <html lang="en">
            <head>
            <meta charset="utf-8">
            <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
            <title>Checkout 3D Simulator</title>
            <link rel="stylesheet" type="text/css" href="/3ds2simulator/css/main.css" />
            </head>
            <body>
            <div id="picture-less-loading-container">
            <div id="picture-less-loading">
            </div>
            </div>
            <div class="container">
            <span class="main-title">Simulator</span>
            <div class="wrap">
            <div class="logo"><img src="/3ds2simulator/images/logo.jpg" alt="Checkout.com" title="Checkout.com" /></div>
            <p class="title text-center">3D-Secure 2 Authentication</p>
            <p class="disclaimer text-center">Please enter your password</p>
            <form id="form" method="post" action="/3ds2simulator/acs/challenge-submit">
            <input type="hidden" name="transactionId"/>
            <div class="input-wrap">
            <i class="glyph-icon ckoicon-lock"></i>
            <input id="password" type="password" name="password" class="form-field" placeholder="Hint: Checkout1!" />
            </div>
            <input type="submit" value="Continue" class="btn" id="txtButton" />
            </form>
            </div>
            </div>
            <script type="text/javascript" src="/3ds2simulator/js/main.js"></script>
            </body>
            </html>

            The challenge is dependent on the card issuer, so the actual HTML may look different, but there should be a form for the cardholder to complete the challenge.

            Notification of outcome

            If you want to be notified about the completion of the challenge, you can register an event handler on your page as follows:

            1
            window.addEventListener("message", messageCallback, false);

            Where messageCallback is a function with the following signature:

            1
            2
            3
            function messageCallback(event){
            console.log(event.data)
            }

            And event.data will contain the following object:

            1
            2
            3
            4
            {
            "transStatus": "Y",
            "threeDSServerTransID": "352455b7-b3b1-4696-a916-69e2e4274e6c"
            }

            Where threeDSServerTransID is the transaction_id of the session and transStatus is one of the following values:

            ValueDescription

            Y

            Authentication/Verification Successful

            N

            Not Authenticated/Account Not Verified (transaction denied)

            U

            Authentication/Account Verification Could Not Be Performed (a technical or other problem, as indicated in ARes or RReq)

            A

            Attempts Processing Performed (not authenticated/verified, but a proof of attempted authentication/verification is provided)

            R

            Authentication/Account Verification Rejected (issuer has rejected transaction)

            Challenge completed

            Once the challenge has been completed, the session should move to a final state, allowing you to (optionally) complete the session.

            At this point the session should contain the eci and cryptogram (CAVV/AVV) properties needed for authorization, but these will only be returned when retrieving the session using a JWT token and not the session_secret. This is to protect them from leaking to the client side.

            The challenge flow should be completed within 15 minutes of initiating the flow. If this is not the case, the status of the challenge can be set to U.


            Step 5 b: 3DS1 challenge (browser only)

            This is only relevant for browser-based authentications.

            If you have 3DS protocol 1.0.2 enabled for processing, there is a chance your session will be downgraded from 3DS2 to 3DS1. This can happen because the card or the issuer was not enrolled for 3DS2, your processor is only set up for 3DS1, or there was an issue while communicating with the 3DS2 Directory Server.

            Depending on the specific scenario, this can happen:

            • Immediately after creating the session

            • After collecting browser data and performing the issuer fingerprint, so essentially instead of a 3DS2 challenge described above.

            When this downgrade happens your session will typically look like this:

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13
            14
            15
            16
            17
            18
            19
            20
            21
            22
            23
            24
            25
            26
            27
            28
            29
            30
            31
            {
            "id": "sid_czh2caqsczxufdjpgojfop3upy",
            "transaction_id": "02a14f16-1612-426f-8d2f-3392573f747e",
            "amount": 10,
            "currency": "USD",
            "completed": false,
            "authentication_type": "regular",
            "authentication_category": "payment",
            "status": "challenged",
            "protocol_version": "1.0.2",
            "next_actions": [
            "authenticate"
            ],
            "challenged": true,
            "transaction_type": "goods_service",
            "session_secret": "sek_PEX6+C6bwZiLbYauPEuN6ix4fyhKvl9l7gV9mVrNX3U=",
            "scheme": "visa",
            "pareq": "eJyNVNtSqzAUffcrMrw6kBuFthPiVDsdq9ZLb0cfEUJhFFoDaPXrDWnrnDNHJbzATtba7LVv7GSbP4NXIctsXQQWdpAFRBGt46xYBdZiPrK71gk%2fAv8%2fbJ5KIYYzEdVSfIvQqIkoy3AlQBYHFiIhdhPs2djDxHaJl9jdmCQ2pT3S8Wniu76wfnSl3d0OpuLlV4iG7QVxpcchDB7MVt5EyCgNi6oVqdFh9HI6vubU9%2f0OYnBvGlFzIcdDjg4PQS6lPoO7YyMPRZgLnu%2fjBcusDAGNS0AcFYm%2bM%2fISreuiku%2b8SzwGD4YRs5bPPK2qTdmHUL%2brsHLqEhKkAmguW5MNjbPNbusGWRqK2mYxHz0dp4N0%2fOcRXV5ffdzMlh89lOSjPMaTgMEGYeQqDivBiaoP6hIf4E6foj7qMajPzZokb7LKkYPBYjZUXbKzjbibRvZgR8AqrX%2fbZuWtpVTjrOrrKvqXZcQV2826EOpPaoC%2bvtuLalwqdnZuOmZRpaYCXixPp9HD%2bXzp3d2vzi7up28iuluMBqunoBk%2bDTJVlqk2R4QiLS0z6HkGW8JVyn%2fdTU2761X4%2fTaF%2f6zTT1fXJcw%3d",
            "xid": "Fk+hAhIWb0KNLzOSVz90fmFmd1M=",
            "_links": {
            "self": {
            "href": "https://3ds2.ckotech.co/sessions/sid_czh2caqsczxufdjpgojfop3upy"
            },
            "acs_url": {
            "href": "https://3ds2.ckotech.co/3ds1simulator/visa/ds/challenge?p=4484070000035519"
            },
            "term_url": {
            "href": "https://3ds2.ckotech.co/sessions/sid_czh2caqsczxufdjpgojfop3upy/pares"
            }
            }
            }

            The next_action is authenticate and the protocol version is 1.0.2. The 3DS1 flow always contains a challenge and the challenge is always browser-based. Let us see how to initiate the challenge.

            Render the challenge

            To render the challenge you need to POST the following form fields to the session._links.acs_url:

            Field nameDescription

            MD

            The session.transation_id.

            TermUrl

            The URL for the handler that will receive the PaRes (Payer Authentication Response) message. We recommend using session._links.term_url for this if you do not wish to build your own handler, but you can also receive the message on your end and forward it to our term_url.

            PaReq

            The Payer Authentication Request (session.pareq). This is the base64 and URL-encoded payload to send to the ACS.

            The above fields can be case-sensitive depending on the ACS, so please make sure to follow the casing shown.

            The result of this POST will be the challenge form. Once the cardholder completes this successfully, the TermUrl will receive the PaRes (Payer Authentication Response) and the outcome of that will be rendered in place of the challenge (see next section).

            Notification of outcome

            If you want to be notified about the completion of the challenge, you can register an event handler on your page as follows:

            1
            2
            3
            4
            5
            window.addEventListener("message", messageCallback, false);
            Where messageCallback is a function with the following signature:
            function messageCallback(event){
            console.log(event.data)
            }

            event.data will contain the following object:

            1
            2
            3
            4
            {
            "status": "approved",
            "transaction_id": "352455b7-b3b1-4696-a916-69e2e4274e6c"
            }

            Where transaction_id is the transaction ID of the session and status is the final status of the session based on the outcome of the challenge.

            If an unexpected error occurred during the validation of the PaRes, the event data will look like this instead:

            1
            2
            3
            4
            5
            {
            "request_id":"0HM2GJLG46GM1:00000001",
            "error_type":"operation_not_allowed",
            "error_codes":["update_not_allowed_due_to_state"]
            }

            Similar to an error Sessions API would respond with.

            Challenge completed

            Once the 3DS1 challenge has been completed, the session should move to a final state, allowing you to (optionally) complete the session.

            At this point the session should contain the eci, xid, and cryptogram (CAVV/AVV) properties needed for authorization, but these will only be returned when retrieving the session using a JWT token and not the session_secret. This is to protect them from leaking to the client side.

            The challenge flow should be completed within 15 minutes of initiating the flow. If this is not the case, the status of the session will be set to challenge_abandoned.


            Step 6: Complete session (optional)

            This is an optional step providing an easy way for you to be notified about the completion of the authentication.

            Once the session is in a final state (approved, declined, rejected, unavailable, or attempted), you can choose to complete it.

            This triggers a POST to the completion.callback_url field of the session and will respond with 204 if the call was successful or 500 otherwise. Alternatively, you can GET the session details to inspect it and verify its final status.

            Endpoints

            For the full API specification, see the API reference.

              post

              https://api.checkout.com/sessions/{session_id}/complete

              Copied!

              The response

              If successful, we will use the callback_url to share the authentication outcome with you (see example below). If we receive a 2XX response from you, you will then get a successful 204 response with no content. If the payment was authenticated, you're now ready to authorize and complete the payment.

              If the authentication is approved (“response_code”: “Y”) or attempted (“A”), you can authorize the payment. If the authentication is unavailable due to technical issues (“U”), you can decide whether or not to proceed with the payment, based on your risk assessment.

              Example authentication outcome

              With the introduction of 3DS version 2.2.0, you may receive a 2.2.0 value in the protocol_version field in the response.

              1
              2
              3
              4
              5
              6
              7
              8
              9
              10
              11
              12
              13
              14
              15
              16
              {
              "session_id": "sid_llraltf4jlwu5dxdtprcv7ba5i",
              "amount" : 6540,
              "currency": "USD",
              "status": "approved",
              "authentication_type": "regular",
              "authentication_category": "payment",
              "reference": "ORD-5023-4E89",
              "approved": true,
              "protocol_version": "2.1.0",
              "response_code": "Y" ,
              "response_reason": "01",
              "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=",
              "eci": "05",
              "challenged": true
              }
              Field nameDescription

              session_id

              string, 36 chars

              The unique identifier for the session.

              amount

              integer

              The amount in the major currency.

              currency

              string

              The three-letter ISO currency code.

              status

              string (enum)

              Indicates the status of the session.

              One of:

              • challenge_abandoned
              • expired
              • approved
              • attempted
              • unavailable
              • declined
              • rejected

              authentication_type

              string

              Indicates the type of payment this session is for.

              authentication_category

              string (enum)

              Indicates the category of the authentication request.

              One of:

              • payment
              • non-payment

              reference

              string, maximum 100 chars

              A reference you can later use to identify this payment, such as an order number.

              approved

              boolean

              Indicates whether the authentication was successful.

              protocol_version

              string, maximum 50 chars

              The 3DS version used for authentication.

              Possible values:

              • 1.0.2
              • 2.1.0
              • 2.2.0

              response_code

              string (enum)

              The response from the DS or ACS which indicates whether a transaction qualifies as an authenticated transaction or account verification.

              One of:

              • Y: authentication verification successful
              • N: not authenticated / account not verified; transaction denied
              • U: authentication/ account verification could not be performed; technical or other problem, as indicated in ARes or RReq
              • A: attempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided
              • C: challenge required; additional authentication is required using the CReq/CRes
              • D: challenge required; decoupled authentication confirmed
              • R: authentication / account verification rejected; issuer is rejecting authentication / verification and requests that the authorization not be attempted
              • I: informational only; 3DS requestor challenge preference acknowledged

              response_reason

              string

              The response from the direct server (DS) or access control server (ACS) which provides information on why the response_code field has the specified value

              • 01: card authentication failed
              • 02: unknown device
              • 03: unsupported device
              • 04: exceeds authentication frequency limit
              • 05: expired card
              • 06: invalid card number
              • 07: invalid transaction
              • 08: no card record
              • 09: security failure
              • 10: stolen card
              • 11: suspected fraud
              • 12: transaction not permitted to cardholder
              • 13: cardholder not enrolled in service
              • 14: transaction timed out at the ACS
              • 15: low confidence
              • 16: medium confidence
              • 17: high confidence
              • 18: very high confidence
              • 19: exceeds ACS maximum challenges
              • 20: non-payment transaction not supported
              • 21: 3RI transaction not supported
              • 22: ACS technical issue
              • 23: decoupled authentication required by ACS but not requested by 3DS requestor
              • 24: 3DS requestor decoupled max expiry time exceeded
              • 25: decoupled authentication was provided in insufficient time to authenticate the cardholder. ACS will not make attempt.
              • 26: authentication attempted but not performed by the cardholder

              cryptogram

              string, 28 chars

              A payment system-specific value provided as part of the access control server (ACS) registration for each supported direct server (DS).

              eci

              string, 2 chars

              The electronic commerce indicator (ECI).

              challenged

              boolean

              Indicates whether this session involved a challenge.

              Session properties

              Session statuses

              Below are the possible values of the status field, which tell you the current status of the session.

              Field nameDescription

              pending

              Authentication has been requested and the session has been started. The session id is passed back to your server and can be shared with the mobile app (iOS or Android) SDK.

              processing

              The 3DS server has updated the authentication with channel data collected by the SDKs and has created and sent an authentication request to the directory server. The access control server is now evaluating the data to decide whether to authenticate the transaction (frictionless) or challenge it.

              approved

              The payment has been successfully authenticated (frictionless or challenged).

              attempted

              The payment has not been successfully authenticated, because the access control server could not be reached, but proof of the attempted authentication is provided (frictionless).

              unavailable

              Authentication failed because of technical problems with the directory server or the issuer's access control server.

              declined

              The transaction was not authenticated. The issuer denied the transaction.

              rejected

              The transaction was rejected. The issuer is rejecting the authentication and requests that authorisation not be attempted.

              challenged

              Authentication has been requested but the issuer requires that the cardholder be presented with a challenge.

              challenge_abandoned

              Authentication has been started and challenged, but the cardholder did not complete the challenge.

              expired

              Authentication has been started but the channel data could not be collected, meaning an authentication request was not created.

              Next actions

              Below are the possible values for the next_actions field. When present, they identify what action to take in order to complete the session.

              Session typeActionDescriptionChannel

              Non-hosted

              collect_channel_data

              Indicates that the SDK should collect the device data and pass it to the Sessions API so that the 3DS server can create an authentication request.

              Browser and app

              issuer_fingerprint

              The issuer fingerprint is a step where the 3DS Method URL is used by the access control server before the authentication request to gather additional browser information to perform the risk assessment of the transaction. The use of the 3DS Method URL is optional.

              Browser only

              challenge_cardholder

              This occurs after an issuer decides to challenge an authentication. You should create a challenge request and submit it to the issuer's access control server to obtain the details to render a challenge window for the cardholder to submit their credentials.

              Browser and app

              Hosted and non-hosted

              complete

              No further actions are required. You can complete the session.

              Browser and app


              Additional authentication data

              When requesting a session, you can add additional data fields to increase the chances of a frictionless authentication. Below is a summary of the optional data you can add to your request.

              Type of dataDescription and examples

              Client user data

              Data that supports the specific authentication and information about the authentication method used.

              For example, your own credentials, and the issuer's credentials.

              Prior transaction information

              For returning users and recurring transactions, gather and submit data with each following transaction.

              For example, when the recurring payment plan expires, payment references, and the authentication method used.

              Account type

              The account type used in your request. Issuer's attach different risk profiles to different accounts.

              For example, credit or debit.

              Address match

              Indicates whether the cardholder's shipping and billing address are the same.

              For example, how long they've had an account with you, and the number of purchases they've made in the last six months.

              User purchase history

              Details of the cardholder's purchase history.

              For example, the number of purchases in the last six months, and the number of card attempts in the last 24 hours.

              Shipping address usage

              Information about the use of the shipping address.

              For example, when the shipping address was first used, and whether the address name matches the cardholder's name.

              Suspicious account activity

              Indicates whether you've experienced any suspicious activity on the cardholder's account.

              Cardholder information

              Additional information you want to provide about the cardholder and their account with you.

              Cardholder email address

              The email address associated with the cardholder's account.

              Cardholder shipping address

              The cardholder's full shipping address.

              Installment payment data

              For transactions that are being paid in installments, you can provide information about the maximum number of authorizations permitted within that payment plan.

              Pre-paid and gift card transactions

              Information about pre-paid or gift card transactions.

              For example, the gift card amount, and whether or not the cardholder is pre-ordering a product.

              Shipping method

              Indicate the shipping method being used for the order, or flag non-shippable items, like digital goods.

              For example, whether it's being shipped to a verified address on file, or being picked up by the cardholder from a local store.

              Delivery information

              Information about the delivery, like the delivery email address or delivery timeframe.