Non-hosted sessions
Last updated: December 17, 2025
Non-hosted sessions enables you to have full control over your 3D Secure (3DS) authentication flow. Sessions are initiated by your back end. You can use them for authentications initiated for both browsers and mobile apps.
Information
See also 3DS exemptions.
- Request a session.
- Get the session's details.
- Calculate the issuer fingerprint (browser channel only).
- Collect the channel data.
- Handle the 3DS challenge (browser channel only).
- Optionally, complete the session.
You can authenticate your non-hosted sessions requests using either access tokens or a session secret.
The Sessions API accepts a valid JSON web token (JWT) bearer token. You can generate these short-lived tokens using the client ID and secret you received when you created your account.
Tokens must contain one of the following scopes, or both if you're unsure of the channel when requesting the session:
sessions:browser– For browser channel flowssessions:app– For native mobile app channel flows
Creating a new session returns a session_secret property, which is a short-lived, randomly generated string that you can only use for actions on that specific session.
You can use the secret in the Authorization header of subsequent requests for that session.
All Sessions API endpoints that you call after creating the session also accept its session secret.
The session_secret is short-lived to reduce the chance of it being leaked to malicious third parties.
The front end does not have access to the client secrets required to create JWT tokens.
Information
Any endpoint accessible with the session_secret can also be accessed with a valid JWT.
This can be useful if you call the endpoints from your back end, because you proxy the requests instead of making them directly from the front end.
Call the Request a session endpoint from your back end, and authenticate with an access token.
In the request body, always provide the following:
currencyfield – The payment currency.sourceobject – The source of the authentication.completionobject – The details for callbacks or redirects after completing the payment.
For initial customer-initiated transactions (CITs) to set up recurring or installment payments in regions that require Strong Customer Authentication (SCA), you must apply a 3DS challenge.
For Visa payments:
- Set
authentication_typetoregular. - Do not provide the
recurringorinstallmentobject.
For all other card schemes:
- Set
authentication_typetorecurringorinstallment. - Provide the
recurringorinstallmentobject respectively, with the following required fields:number_of_payments– Forinstallmentpayments, The agreed total number of payment installments over the duration of the installment agreement.days_between_payments– The minimum number of days between authorizations. If not specified, the default1is applied.expiry– The end date for authorizations. If not specified forrecurringpayments, the default date99991231is applied.
For non-recurring or non-installment payments, if you provide these fields the API ignores them.
If you create a session and provide the channel_data, you do not need to collect and update the channel data later on.
To use 3DS version 2.2.0, provide the javascript_enabled field.
To increase the likelihood of frictionless authentication, provide the following data:
| Data | Description |
|---|---|
Client user data | The details of the specific authentication and the authentication method used. For example, your own credentials, and the issuer's credentials. |
Prior transaction information | For returning users and recurring transactions, the details of previous transactions. For example, when the recurring payment plan expires, payment references, and the authentication method used. |
Account type | The account type used in your request. For example, credit or debit. Issuers attach different risk profiles to different accounts. |
Address match | Indicates whether the cardholder's shipping and billing address are the same. |
User purchase history | The 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 | The details of previous 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 | Any additional details 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, the maximum number of authorizations permitted on that payment plan. |
Prepaid and gift card transactions | The details of prepaid or gift-card transactions. For example, the gift card amount, and whether or not the cardholder is pre-ordering a product. |
Shipping method | The shipping method used for the order, or any non-shippable items such as 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 | The details of the delivery. For example, the delivery email address or delivery time frame. |
post
https://api.checkout.com/sessions
If successful, you receive a 202 - Accepted response, with pending status.
The response also returns:
id– The session ID, prefixed withsid_, which you need to get the session details.status– If successful, the status ispending. See also Session statuses._links.three_ds_method_url– A URL to redirect the cardholder to in order to complete the Issuer Fingerprint, if supported by the card.next_actions– The actions you need to take to complete the session. See Next actions.protocol_version– With the introduction of 3DS version 2.2.0, you may receive a2.2.0value in this field.
Note
If the card is not enrolled in 3DS with the selected scheme, you receive a 422 response and a card_not_enrolled error.
To continue to payment authorization, you can process the transaction as a non-3DS payment by setting 3ds.enabled to false in your payment request.
The next_actions array can contain the following values:
| Action | Description | |
|---|---|---|
| Non-hosted | ||
| Indicates that the SDK needs to collect the device data and pass it to the Sessions API so that the 3DS server can create an authentication request. | |
| Before the authentication request, the access control server (ACS) uses the 3DS Method URL to gather additional browser information to perform the risk assessment of the transaction.
Using the 3DS Method URL is optional. | |
| After the issuer decides to challenge the authentication, create a challenge request and submit it to the issuer's ACS to obtain the details to render a challenge window for the cardholder to submit their credentials in. | |
| Hosted and non-hosted | ||
| No further actions are required. You can complete the session. | |
Sessions can have the following statuses:
| Status | Description |
|---|---|
| Successful authentication | |
| Authentication has been requested and the session has started. The session |
| The 3DS server has:
The access control server is evaluating the data to decide whether to authenticate the transaction (frictionless) or challenge it. |
| The payment was authenticated by a stand-in service, because the ACS was unavailable or does not support 3DS natively. You can treat this as a successful authentication and proceed to authorization. |
| Authentication has been requested but the issuer requires you to challenge the cardholder. |
| The payment has been successfully authenticated (frictionless or challenged). |
| Unsuccessful authentication | |
| Authentication started and a challenge presented, but the cardholder did not complete the challenge. |
| The transaction was not authenticated. The issuer denied the transaction. |
| Authentication started but the channel data could not be collected, so no authentication request was created. |
| The transaction was rejected. The issuer rejects the authentication and requests that authorization not be attempted. |
| Authentication failed because of technical problems with the directory server or the issuer's ACS. |
Information
You can skip this step if your back end forwards the Request a session response to your front end.
Collect the device details of the browser or app that initiated the session to include in the authentication request.
Call the Get session details endpoint, and provide the session ID returned in the Request a session response as the {session_id} path parameter.
get
https://api.checkout.com/sessions/{session_id}
The response returns the next actions and session status.
Information
This is for the browser channel only.
If the Get session details response does not return a three_ds_method_url property, Sessions automatically sets the three_ds_method_completion property to U and continues the flow.
You do not need to make a POST request to the /issuer-fingerprint endpoint.
This returns the next actions and session status.
If one of the next actions is issuer_fingerprint, the customer's browser must contact the issuer's ACS directly to calculate its fingerprint.
- Construct the following base64 encoded payload:
- Send the payload to the
three_ds_method_urlproperty of the session's_linksobject using aPOSTrequest and putting the base64 encoded data in athreeDSMethodDataform field.
This triggers a POST redirect to the threeDSMethodNotificationURL with a threeDSMethodData form parameter.
This is a base64 encoded payload that, when decoded, looks as follows:
If you do not want to handle the notification manually, you can use Checkout.com's interceptor application instead.
Set the threeDSMethodNotificationURL to the applicable endpoint:
post
https://api.checkout.com/sessions-interceptor/3ds-method-notification
After you POST the threeDSMethodData, you can be notified of completion by listening for a browser event as follows:
messageCallback is a function that has the following signature:
event.data contains the following object:
To update the three_ds_method_completion property, send a POST request to the issuer_fingerprint property of the session's _links object.
When you receive the message, the fingerprint has completed successfully.
You can set the three_ds_method_completion property to Y.
If you do not receive the message within 10 seconds of initiating the flow, set the three_ds_method_completion property to N.
You must implement a timeout logic to account for this.
Information
The response you receive from the completion notification only contains 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 you did not provide the channel data when you created and you need to submit this data after calculating the issuer fingerprint, you can make a single POST request to /sessions/{id}/collect-data (see Collect channel data) with the three_ds_method_completion property in the payload.
You do not then need to make a separate PUT request to /sessions/{id}/issuer-fingerprint.
Information
You can skip this step for app channels, if you provided the channel data when you created the session. It is handled by Checkout.com's mobile SDKs.
Once you've completed the next_actions, update the session with the collected device data to make the authentication request.
Call the Update a session endpoint, and provide the session ID as the {id} path parameter.
3DS version 2.2.0 introduced a channel_data.javascript_enabled field.
If you do not provide this field in the request, Checkout.com adds it with the default value true.
put
https://api.checkout.com/sessions/{session_id}/collect-data
In the request body, provide the following fields:
| Field name | Description |
|---|---|
required string | Indicates the interface (either |
required string | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder’s browser. |
required boolean | Boolean that represents the ability of the cardholder browser to execute Java. The value is returned from the |
optional boolean | Boolean that represents the ability of the cardholder browser to execute JavaScript. Default: |
required string | Value representing the browser language as defined in IETF BCP47. Returned from the |
required string | Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from the cardholder's browser using the |
required string | Total height of the cardholder’s screen in pixels. Value is returned from the |
required string | Total width of the cardholder’s screen in pixels. Value is returned from the |
required string | Time difference between UTC time and the local time of the cardholder's browser, in minutes. |
required string | Exact content of the HTTP user-agent header. |
required string | IP address of the browser as returned by the HTTP headers to the 3DS Requestor. |
optional string | Indicates whether the 3DS Method successfully completed.
|
Once you've updated the session, Checkout.com sends the authentication request. The issuer returns a response that includes:
- The authentication outcome – This can be one of:
approved,attempted,challenged,declined,rejected, orunavailable. - The next actions – This can be
challenge_cardholderorcomplete. - The session status – If successful, the status is
processing. If the authentication was started but could not be completed, it isexpired. exemptionobject – If the authentication request included a 3DS exemption that was successfully applied.
Information
For browser channel only. You can skip this step for app channel because Checkout.com's mobile SDKs handle the challenge flow.
If, after calculating the issuer fingerprint and collecting the channel data, the authentication is approved or declined immediately (frictionless flow), you can proceed to complete the session.
If not, the cardholder is challenged to provide additional information to authenticate the payment (challenge flow).
If next_actions contains challenge_cardholder, follow these steps:
- Create the challenge request (CReq) message as follows:
The challengeWindowSize can be one of the following values:
| Challenge window size value | Size |
|---|---|
01 | 250–400px |
02 | 390–400px |
03 | 500–600px |
04 | 600–400px |
05 | Full screen |
Information
The challenge window style depends on the issuer, so the window size may not be exact. We recommend that you render the challenge inside a frame to have full control over the final size on your page.
- Once the CReq message is constructed, base64 encode it and
POSTit to the session'sacs.urlproperty, in acreqform field. Ensure that the encoded CReq message does not contain any padding.
If the CReq message is successful, the response returns the HTML needed to render the challenge. For example:
Information
The challenge depends on the card issuer, so the actual HTML may look different. A form for the cardholder to complete the challenge is expected.
If you want to be notified about the completion of the challenge, you can register an event handler on your page as follows:
messageCallback is a function that has the following signature:
event.data contains the following object:
threeDSServerTransID is the transaction_id.
transStatus is one of the following values:
| Value | Description |
|---|---|
| Authentication/Verification Successful |
| Not Authenticated/Account Not Verified (transaction denied) |
| Authentication/Account Verification Could Not Be Performed (a technical or other problem, as indicated in ARes or RReq) |
| Attempts Processing Performed (not authenticated/verified, but a proof of attempted authentication/verification is provided) |
| Authentication/Account Verification Rejected (issuer has rejected transaction) |
Once the challenge is completed, the session moves to a final state. Optionally, you can complete the session.
The challenge flow completes within approximately 15 minutes after initiation.
If this is not the case, you can set the challenge status to U.
If you retrieve the session using a JWT (not the session_secret), it contains the eci and cryptogram (CAVV/AVV) properties needed to authorize the payment.
This protects this data from leaking to the client side.
Information
This step is optional. It enables you to be notified when authentication is completed.
Once the session is in a final state (approved, attempted, declined, rejected, or unavailable), you can complete the session.
This triggers a POST to the session's completion.callback_url field.
If successful, you receive a 204 response.
If unsuccessful, you receive a 500 response.
Alternatively, you can GET the session details to inspect it and verify the final status.
Call the Complete a session endpoint, and provide the session ID as the {session_id} path parameter.
post
https://api.checkout.com/sessions/{session_id}/complete
If successful, Checkout.com uses the callback_url to share the authentication outcome with you in the response.
If you return a 2XX response, you then receive a successful empty 204 response.
If the authentication is:
- Approved (
"response_code": "Y") or attempted ("A") – You can authorize and complete the payment. - Unavailable due to technical issues (
"U") – You can decide whether or not to proceed with the payment, based on your risk assessment.
With the introduction of 3DS version 2.2.0, you may receive a 2.2.0 value in the protocol_version field of the response.
| Field name | Description |
|---|---|
string | The unique identifier for the session. |
integer | The amount in the major currency unit. |
string | The payment currency. |
string | The session's status. This can be one of:
|
string | The type of payment the session is for. |
string (enum) | The category of the authentication request. This can be one of:
|
string | Your reference for the payment. |
boolean | Indicates whether the authentication was successful. |
string | The 3DS version used for authentication. Possible values:
|
string (enum) | The response from the direct server (DS) or ACS which indicates whether the transaction qualifies as an authenticated transaction or account verification. This can be of:
|
string | The response from the DS or ACS that provides information on why the This can be one of:
|
string | A payment system-specific value provided as part of the ACS registration for each supported DS. |
string | The electronic commerce indicator (ECI). |
boolean | Indicates whether this session involved a challenge. |