Non-hosted sessions

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

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.

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

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.

For the full API specification, see the API reference.

{
  "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"
  }
}

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

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.

{
  "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"
    }
  }
}

In your API request, set authentication_type to recurring.

You will also need to send the recurring object with the following required fields:

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

{
  "source": {
    "type": "card",
    "number": "4485040371536584",
    "expiry_month": 1,
    "expiry_year": 2030
  },
  "amount": 100,
  "currency": "USD",
  "authentication_type": "recurring",
  “recurring:”{
     “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"
  }
}

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.

For the full API specification, see the API reference.

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

See below for all possible actions and their meanings.

See below for all possible statuses and their meanings.

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 will continue the flow. The following actions will be collect_channel_data, challenge_cardholder, or complete.

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.

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

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

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:

{
  "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:

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

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

Where messageCallback is a function with the following signature:

function messageCallback(event){
  console.log(event.data)
}

And event.data will contain the following object:

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

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.

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.

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.

For the full API specification, see the API reference.

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.

See below for all possible actions and their meanings.

See below for all possible statuses and their meanings.

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.

{
  "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"
    }
  }
}

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

{
  "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
}

Once the CReq message is constructed, it needs to be base64 encoded and posted to the acs.url property of the session in a form field named creq. If successful, the response will be the HTML needed to render the challenge.

<!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>

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

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

Where messageCallback is a function with the following signature:

function messageCallback(event){
  console.log(event.data)
}

And event.data will contain the following object:

{
  "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:

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

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:

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

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

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

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

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

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:

{
  "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:

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

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

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.

For the full API specification, see the API reference.

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.

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.

{
 "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
}

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

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

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.

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

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

For example, credit or debit.

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

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

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

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

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