Sessions API

The Sessions API is a standalone solution to authenticate online transactions with the EMV 3D Secure (3DS) protocol, allowing you to implement smarter 3DS authentication flows.

It gives you greater visibility of the issuers' authentication decisions and provides a smoother experience for your customers, while helping you to fulfil the Strong Customer Authentication (SCA) requirements of the second Payment Services Directive (PSD2). And if the issuer does not support the latest version of 3DS, Sessions allows you to fallback to 3DS version 1.0 instead.

Once you have completed the authentication via Sessions, you can then authorize the payment through our payment gateway or another payment services provider (PSP).

You can choose from two solutions: non-hosted or hosted.

📘
Supported card schemes
Sessions currently supports Visa (Verified by Visa / Visa Secure), Mastercard (Identity Check), American Express (SafeKey), and Discover (ProtectBuy). We will soon add support for additional schemes, including Cartes Bancaires (Fast'R) and JCB (J/Secure).

👍
If you already use our Payments API to process transactions, you don't need to make any changes to your integration. When creating a payment, simply make a request with 3ds.enabled set to true and it will be 3DS authenticated via our hosted solution. See our 3D Secure integration guide for more information.

Non-hosted and hosted sessions

Non-hosted

Non-hosted sessions are designed for those who want full control over their authentication flow.

Initiate an authentication through the Sessions API using a card or a network token, set completion.type to non-hosted and provide completion.callback_url to receive the authentication result.

You will then need to collect channel (either browser or mobile app) and additional authentication data, perform a challenge (if required), and handle the authentication result. You can then proceed to authorize the payment, either through our payment gateway or another PSP.

Get started with non-hosted sessions.

Hosted

This is the simplest solution, where we manage the authentication flow for you.

Initiate an authentication through the Sessions API, set completion.type to hosted, provide completion.success_url and completion.failure_url, and redirect the customer using the link in the response. We'll then gather the necessary payment, device and cardholder data and take care of the rest.

Get started with hosted sessions.

Non-hosted session: browser or mobile authentication

If you want full control over the authentication flow, use non-hosted sessions. These will be initiated from your server.

Step 1: Request a session

The request

Endpoints

Live

POSThttps://api.checkout.com/sessions

Sandbox

POSThttps://api.sandbox.checkout.com/sessions

Header parameters

Header	Value
`Authorization` Required	`secret key` Use the valid secret key of your Checkout.com account. You can find this in the Hub.
`Content-Type`\ Required	`application/json`

Body parameters

📘
The table below shows an example of a session created from a browser with a card, and only describes the minimum recommended fields.

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

Field name	Description
`source` Object required	Details about the payment source.
`source.type`\ string\ required	The type of payment source (`card` or `network_token`).
`source.card`\ string\ required	The card number (without separators).
`source.expiry_month`\ integer\ required	The expiry month of the card.
`source.expiry_year`\ integer\ required	The expiry year of the card
`source.name`\ string\ optional	The name of the cardholder.
`source.billing_address`\ object\ optional	The billing address of the cardholder.
`source.phone`\ object\ conditional	The phone number of the cardholder.\ Required in some countries.
`amount`\ integer\ optional	The payment amount in your chosen currency. Omit the amount or provide a value of `0` to perform a card verification. The format depends on the currency. For more information, see calculating the value.
`currency`\ String\ required	The three-letter ISO currency code.
`authentication_type`\ String\ optional	Indicates the type of payment this session is for.\ Default: `regular`.
`authentication_category`\ String\ optional	Indicates the category of the authentication request.\ Default: `payment`.
`challenge_indicator`\ String\ optional	Indicates whether a challenge is requested for this session. Possible values: `no_preference`, `no_challenge_requested`, `challenge_requested`, `challenge_requested_mandate`.\ Default: `no_preference`.
`reference`\ String\ optional	A reference you can later use to identify this payment, such as an order number.
`transaction_type`\ String\ optional	Identifies the type of transaction being authenticated.\ Default: `goods_service`.
`completion`\ Object\ required	The redirect information needed for callbacks or redirects
`completion.type`\ String\ required	Whether or not the session should be hosted by Checkout.com. Set this to `non_hosted`.
`completion.callback_url`\ String\ required	Specifies the URL to be called once the session is complete.

Request example

{
  "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": "London",
    "zip": "W1T 4TJ",
    "country": "GB"
  },
  "completion": {
    "type": "non-hosted",
    "callback_url": "https://example.com/sessions/callback"
  }
}

The response

You should receive a 202 - Accepted response, with a status of pending. It will also contain the session id (starting sid_), which you'll use to get the session details in the next step, and a _links.fingerprint URL, where the cardholder should be redirected to load the 3DS Method.

Field name	Description
`id` string	The unique session identifier.
`transaction_id`\ string	The transaction identifier. This needs to be provided when communicating directly with the issuing bank's access control server (ACS).
`amount`\ integer	The payment amount.
`currency`\ string	The three-letter ISO currency code.
`authentication_type`\ string	Indicates the type of payment this session is for.
`authentication_category`\ string	Indicates the category of the authentication request.
`status`\ string	The status of the session. Should be `pending`.\ See below for all possible statuses and their meanings.
`next_actions`\ array	Specifies what action to take to complete the session. Will be one of: `collect_channel_data`, `issuer_fingerprint` (browser-initiated only), or `challenge_cardholder`.\ See below for all possible actions and their meanings.
`protocol_version`\ string	The 3DS version used for authentication.
`reference`\ string	A reference you can later use to identify this payment, such as an order number.
`_links`\ object	The links related to the session.
`_links.self`\ object	The URL of the session.
`_links.fingerprint`\ object	The URL of the issuer fingerprint (3DS Method).

Response example

{
  "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"
    },
    "issuer_fingerprint": {
      "href": "http://3ds2.cko.lon/3ds2simulator/acs/3ds-method"
    }
  }
}

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 a authentication request. To do so, get the current session details with the following request.

The request

Endpoints

Live

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

Sandbox

GEThttps://api.sandbox.checkout.com/sessions/{session_id}

Header and path parameters

Header	Value
`Authorization` Required	`public key` Use the valid public key of your Checkout.com account. You can find this in the Hub.
`Channel`\ Required	`app` or `browser`\ Indicates the source of the authentication (mobile app or browser), influencing which next actions are returned.

Path	Value
`id` required	The session ID, starting `sid_`.

The response

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

Field name	Description
`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`.\ See below for all possible actions and their meanings.
`status`\ String	The status of the session. Should be `pending`.\ See below for all possible statuses and their meanings.

Step 3: Submit 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.

The request

Endpoints

Live

PUThttps://api.checkout.com/sessions/{session_id}/channel-data

Sandbox

PUThttps://api.sandbox.checkout.com/sessions/{session_id}/channel-data

Path parameters

Path	Value
`id` required	The session ID, starting `sid_`.

Body parameters

Browser authentication

🚧
These are the parameters for a browser authentication. See below for a mobile app authentication.

Field name	Description
`channel` String required	Indicates the interface (either `browser` or `app`) being used to initiate the transaction. Set this to `browser`.
`accept_header`\ String\ required	Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser.
`java_enabled`\ boolean\ required	Boolean that represents the ability of the cardholder browser to execute Java. The value is returned from the navigator.javaEnabled property.
`language`\ String\ required	Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.
`color_depth`\ String\ required	Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from cardholder's browser using the screen.colorDepth property.
`screen_height`\ String\ required	Total height of the cardholder’s screen in pixels. Value is returned from the screen.height property.
`screen_width`\ String\ required	Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.
`timezone`\ String\ required	Time difference between UTC time and the local time of the cardholder's browser, in minutes.
`user_agent`\ String\ required	Exact content of the HTTP user-agent header.
`ip_address`\ String\ required	IP address of the browser as returned by the HTTP headers to the 3DS Requestor.
`3ds_method_completion`\ String\ required	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).

App authentication

🚧
These are the parameters for an app authentication. See above for a browser authentication.

Field name	Description
`channel` String required	Indicates the interface (either `browser` or `app`) being used to initiate the transaction. Set this to `app`.
`sdk_app_id`\ String\ required	A unique ID created upon all installations and updates of the 3DS Requestor App on a consumer device. This will be newly generated and stored by the SDK for each installation or update.
`sdk_max_timeout`\ Integer\ required	Indicates the maximum amount of time (in minutes) for all exchanges.
`sdk_ephem_pub_key`\ Object\ required	Public key component of the ephemeral key pair generated by the SDK and used to establish session keys between the SDK and access control server. In the authentication request, this data element is present as its own object. In the authentication response, this data element is contained within the ACS Signed Content JWS object.
`sdk_encrypted_data`\ String\ required	Contains data encrypted by the SDK for the directory server to decrypt.
`sdk_transaction_id`\ String\ required	Unique ID assigned by the SDK to identify a single transaction.
`sdk_interface_type`\ String\ required	Lists all the SDK interface types that the cardholder's device supports for displaying specific challenge user interfaces within the SDK\ Values: `native`, `html`, `both`.
`sdk_ui_elements`\ Array\ required	Lists all the elements that the cardholder's device supports for displaying the challenge user interface within the SDK.\ Values: `text`, `single_select`, `multi_select`, `oob`, `html_other`.

The response

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.

Field name

Description

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.

See below for all possible actions and their meanings.

status\ String

The status of the session. Should be processing. If expired, the authentication was started but could not be completed.\ See below for all possible statuses and their meanings.

Step 4: Complete session

If the payment wasn't challenged (frictionless), the next_actions property will be complete, and you can complete the session with the following request.

If there was a challenge, the next_actions property will be challenge_cardholder. Your SDK must initiate a challenge for the cardholder to complete and then communicate the result by passing it in the challenge request. After the challenge is successfully completed, a challenge response is sent back to you and you can then complete your session.

The request

Endpoints

Live

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

Sandbox

POSThttps://api.sandbox.checkout.com/sessions/{session_id}/complete

Path parameters

Path	Value
`id` required	The session ID, starting `sid_`.

The response

If successful, we will use the callback_url to share the authentication outcome and you will get a 204 response with no content. If the payment was authenticated, you're now ready to authorize and complete the payment.

Hosted session: browser authentication

Step 1: Request a session

The request

To begin, make a session request.

Endpoints

Live

POSThttps://api.checkout.com/sessions

Sandbox

POSThttps://api.sandbox.checkout.com/sessions

Header parameters

Header	Value
`Authorization` Required	`secret key` Use the valid secret key of your Checkout.com account. You can find this in the Hub.
`Content-Type`\ Required	`application/json`

Body parameters

📘
The table below shows an example of a payment with a card, and only describes the minimum recommended fields.

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

Field name	Description
`source` Object required	Details about the payment source.
`source.type`\ String\ required	The type of payment source (`card` or `network_token`).
`source.card`\ String\ required	The card number (without separators).
`source.expiry_month`\ integer\ required	The expiry month of the card.
`source. expiry_year`\ integer\ required	The expiry year of the card.
`source.name`\ string\ optional	The name of the cardholder.
`source.billing_address`\ object\ optional	The billing address of the cardholder.
`source.phone`\ object\ conditional	The phone number of the cardholder.\ Required in some countries.
`amount`\ integer\ optional	The payment amount in your chosen currency. Omit the amount or provide a value of `0` to perform a card verification.\ The format depends on the currency. For more information, see calculating the value.
`currency`\ String\ required	A three-letter ISO currency code representing the currency of the payment.
`authentication_type`\ String\ optional	Indicates the type of payment this session is for.\ Default: `regular`.
`authentication_category`\ String\ optional	Indicates the category of the authentication request.\ Default: `payment`.
`challenge_indicator`\ String\ optional	Indicates whether a challenge is requested for this session. Possible values: `no_preference`, `no_challenge_requested`, `challenge_requested`, `challenge_requested_mandate`.\ Default: `no_preference`.
`reference`\ String\ optional	A reference you can later use to identify this payment, such as an order number.
`transaction_type`\ String\ optional	Identifies the type of transaction being authenticated.\ Default: `goods_service`.
`completion`\ Object\ required	The redirect information needed for callbacks or redirects after the payment is completed.
`completion.type`\ string\ required	Whether or not the session should be hosted by Checkout.com. Set this to `hosted`. When the value is `hosted`, the response will include a redirect link.
`completion.success_url`\ string\ required	For `hosted` sessions, this overrides the default success redirect URL configured on your account.
`completion.failure_url`\ string\ required	For `hosted` sessions, this overrides the default failure URL configured on your account.

Request example

{
  "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": "London",
    "zip": "W1T 4TJ",
    "country": "GB"
  },
  "completion": {
    "type": "hosted",
    "success_url": "http://example.com/sessions/success",
    "failure_url": "http://example.com/sessions/fail"
  }
}

The response

You should receive a 202 - Accepted response with a _links.redirect link.

Field name	Description
`id` string	The unique session identifier.
`transaction_id`\ string	The transaction identifier. This needs to be provided when communicating directly with the issuing bank's access control server (ACS).
`amount`\ integer	The payment amount.
`currency`\ string	The three-letter ISO currency code.
`authentication_type`\ string	Indicates the type of payment this session is for.
`authentication_category`\ string	Indicates the category of the authentication request.
`status`\ string	The status of the session. Should be `pending`.\ See below for all possible statuses and their meanings.
`next_actions`\ array	Specifies what action to take to complete the session. For example: `redirect_cardholder`.\ See below for all possible actions and their meanings.
`protocol_version`\ string	The 3DS version used for authentication.
`reference`\ string	A reference you can later use to identify this payment, such as an order number.
`_links`\ object	The links related to the session.
`_links.redirect`\ object	The link where the cardholder should be redirected to after authentication.
`_links.self`\ object	The URL of the session.

Response example

{
  "id": "sid_y3oqhf46pyzuxjbcn2giaqnb441",
  "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c",
  "amount": 120,
  "currency": "USD",
  "authentication_type": "regular",
  "authentication_category": "payment",
  "status": "pending",
  "next_actions": [
    "redirect_cardholder"
  ],
  "protocol_version": "2.2.0",
  "reference": "ORD-5023-4E89",
  "_links": {
    "redirect": {
      "href": "http://3ds2.checkout.com/interceptor/sid_y3oqhf46pyzuxjbcn2giaqnb44"
    },
    "self": {
      "href": "https://api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441"
    }
  }
}

Step 2: Redirect the customer

Redirect the customer using the _links.redirect URL you received in the response.

In the background, our Sessions API will then gather the device data, perform a challenge (if required), and authenticate the payment. After authentication is completed, your customer will be redirected to your success_url or failure_url. You can now continue to authorize the payment via our Payments API.

Session properties: statuses and next actions

Session statuses

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

Status	Description
`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.
`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 type	Action	Description	Channel
Hosted	`redirect_cardholder`	Redirect the customer so we can handle all the other necessary actions (collect channel data, issuer fingerprint, and challenge) for you.	Browser only\
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
Non-hosted	`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
Non-hosted	`challenge_cardholder`	This occurs after an issuer decides to challenge an authentication. The mobile app or browser SDK 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 data	Description 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.
Cardholder account / user information	Information about the cardholder and their account on your platform.\ 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.

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at [email protected].

📘

Non-hosted and hosted sessions

Non-hosted

Hosted

Non-hosted session: browser or mobile authentication

Step 1: Request a session

The request

Endpoints

Live

Sandbox

Header parameters

Body parameters

📘The table below shows an example of a session created from a browser with a card, and only describes the minimum recommended fields.

👍

Request example

The response

Response example

Step 2: Get session details

The request

Endpoints

Live

Sandbox

Header and path parameters

The response

Step 3: Submit channel data

The request

Endpoints

Live

Sandbox

Path parameters

Body parameters

Browser authentication

🚧These are the parameters for a browser authentication. See below for a mobile app authentication.

App authentication

🚧These are the parameters for an app authentication. See above for a browser authentication.

The response

Step 4: Complete session

The request

Endpoints

Live

Sandbox

Path parameters

The response

Hosted session: browser authentication

Step 1: Request a session

The request

Endpoints

Live

Sandbox

Header parameters

Body parameters

📘The table below shows an example of a payment with a card, and only describes the minimum recommended fields.

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

Request example

The response

Response example

Step 2: Redirect the customer

Session properties: statuses and next actions

Session statuses

Next actions

Additional authentication data

Can we help?

📘
The table below shows an example of a session created from a browser with a card, and only describes the minimum recommended fields.

🚧
These are the parameters for a browser authentication. See below for a mobile app authentication.

🚧
These are the parameters for an app authentication. See above for a browser authentication.

📘
The table below shows an example of a payment with a card, and only describes the minimum recommended fields.

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