# Non-hosted sessions Non-hosted sessions enables you to have full control over your [3D Secure (3DS)](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure.md) authentication flow. Sessions are initiated by your back end. You can use them for authentications initiated for both browsers and mobile apps. --- ## How it works 1. Request a session. 2. Get the session's details. 3. Calculate the issuer fingerprint (browser channel only). 4. Collect the channel data. 5. Handle the 3DS challenge (browser channel only). 6. Optionally, complete the session. --- ## Authentication You can authenticate your non-hosted sessions requests using either access tokens or a session secret. ### Access tokens The [Sessions API](https://api-reference.checkout.com/#tag/Standalone) 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 flows - `sessions:app` – For native mobile app channel flows ### Session secret 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. --- ## Request a session Call the [Request a session](https://api-reference.checkout.com/tag/Standalone/#operation/createSession) endpoint from your back end, and authenticate with an access token. In the request body, always provide the following: - `currency` field – The payment currency. - `source` object – The source of the authentication. - `completion` object – The details for callbacks or redirects after completing the payment. ### Recurring and installment payments For initial customer-initiated transactions (CITs) to set up recurring or installment payments in regions that require [Strong Customer Authentication (SCA)](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/sca-compliance.md), you must apply a 3DS challenge. For Visa payments: - Set `authentication_type` to `regular`. - Do not provide the `recurring` or `installment` object. For all other card schemes: - Set `authentication_type` to `recurring` or `installment`. - Provide the `recurring` or `installment` object respectively, with the following required fields: - `number_of_payments` – For `installment` payments, 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 default `1` is applied. - `expiry` – The end date for authorizations. If not specified for `recurring` payments, the default date `99991231` is applied. For non-recurring or non-installment payments, if you provide these fields the API ignores them. ### Channel data 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. ### 3DS exemptions For more information, see [3DS exemptions](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure/standalone-sessions/3ds-exemptions.md). ### Frictionless authentication 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. | > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/sessions` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/sessions` ### Request example **Regular payments** ```json { "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": "123 Anywhere St.", "address_line2": "Apt. 456", "city": "Anytown", "state": "AL", "zip": "123456", "country": "US" }, "completion": { "type": "non_hosted", "callback_url": "https://example.com/sessions/callback" } } ``` **Recurring and installment payments** ```json { "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": "123 Anywhere St.", "address_line2": "Apt. 456", "city": "Anytown", "state": "AL", "zip": "123456", "country": "US" }, "completion": { "type": "non_hosted", "callback_url": "https://example.com/sessions/callback" } } ``` ### Response example ```json { "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" } } } ``` If successful, you receive a `202 - Accepted` response, with `pending` status. The response also returns: - `id` – The session ID, prefixed with `sid_`, which you need to get the session details. - `status` – If successful, the status is `pending`. See also [Session statuses](#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](#Next_actions). - `protocol_version` – With the introduction of 3DS version 2.2.0, you may receive a `2.2.0` value 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](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout). #### Next actions The `next_actions` array can contain the following values: | Action | Description | | --- | --- | | **Non-hosted** | | | `collect_channel_data` | 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.

Channel – Browser and app

Status – `pending` | | `issuer_fingerprint` | 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.

Channel – Browser only

Status – `pending` | | `challenge_cardholder` | 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.

Channel – Browser and app

Status – `challenged` | | **Hosted and non-hosted** | | | `complete` | No further actions are required. You can complete the session.

Channel – Browser and app

Status – `approved`, `declined`, `rejected`, or `expired` | #### Session statuses Sessions can have the following statuses: | Status | Description | | --- | --- | | **Successful authentication** | | | `pending` | Authentication has been requested and the session has started.

The session `id` is passed back to your server and can be shared with the app's Android or iOS SDK. | | `processing` | The 3DS server has:
- Updated the authentication with channel data collected by the SDKs
- Created and sent an authentication request to the directory server

The access control server is evaluating the data to decide whether to authenticate the transaction (frictionless) or challenge it. | | `attempted` | 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. | | `challenged` | Authentication has been requested but the issuer requires you to challenge the cardholder. | | `approved` | The payment has been successfully authenticated (frictionless or challenged). | | **Unsuccessful authentication** | | | `challenge_abandoned` | Authentication started and a challenge presented, but the cardholder did not complete the challenge. | | `declined` | The transaction was not authenticated. The issuer denied the transaction. | | `expired` | Authentication started but the channel data could not be collected, so no authentication request was created. | | `rejected` | The transaction was rejected. The issuer rejects the authentication and requests that authorization not be attempted. | | `unavailable` | Authentication failed because of technical problems with the directory server or the issuer's ACS. | --- ## Get the session details > **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](https://api-reference.checkout.com/tag/Standalone/#operation/getSession) endpoint, and provide the session ID returned in the Request a session response as the `{session_id}` path parameter. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `GET` `https://{prefix}.api.checkout.com/sessions/{session_id}` **Sandbox** `GET` `https://{prefix}.api.sandbox.checkout.com/sessions/{session_id}` ### Response ```json { "id": "sid_y3oqhf46pyzuxjbcn2giaqnb44", "session_secret": "sek_Dal7UyiH8rIFXA4PfgiIk2jUyQkVDeEWgVBEL4TsRTE=", "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c", "scheme": "visa", "amount": 120, "currency": "USD", "completed": false, "challenged": true, "authentication_type": "regular", "authentication_category": "payment", "certificates": { "ds_public": "eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ik1LQkNUTkljS1VTRGlpMTF5U3MzNTI2aURaOEFpVG83VHU2S1BBcXY3RDQiLCJ5IjoiNEV0bDZTUlcyWWlMVXJONXZmdlZIdWhwN3g4UHhsdG1XV2xiYk00SUZ5TSIsInVzZSI6ImVuYyIsImtpZCI6IjEifQ", "ca_public": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB", "ca_public_all": [ "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxWEvDZRhKEefZ5sQS7RJZXWbSOPxus-ZyLQjtmrrAQawnKI-AG8BKpVdZVGlpcdxCnGbCIy8CKk2Oi7Mgdqfv5R_4_jI7yl4j7Svmh1Sw934eeF9RyB59Ihl36Y0pNfVW9hBqJuq2o8ulrA1TOtpTpje23CY8sjFE5QnJm1evZRB_ZZQ1txl4nrAiHkno4cVJPouBesryVGVQ0zi1bM0P-05Ydgksvph-1nyjnDldD68mejVF69Tijxa22b6BUCXEuPfbXZcW2NpM_W3msnvKiTWFaMlnIzGYIoFnAnCIVU7Min6CPn565tv0iyIt8BrcezsGzefUw17NEq0J4tCvWwIDAQAB" ] }, "status": "challenged", "status_reason": "ares_status", "approved": false, "protocol_version": "2.2.0", "account_info": { "purchase_count": 10, "account_age": "no_account", "add_card_attempts": 10, "shipping_address_age": "this_transaction", "account_name_matches_shipping_name": true, "suspicious_account_activity": true, "transactions_today": 10, "authentication_method": "no_authentication", "cardholder_account_age_indicator": "no_account,", "account_change": "2019-08-24T14:15:22Z", "account_change_indicator": "this_transaction", "account_date": "2019-08-24T14:15:22Z", "account_password_change": "2019-08-24T14:15:22Z", "account_password_change_indicator": "no_change", "transactions_per_year": 2, "payment_account_age": "2019-08-24T14:15:22Z", "shipping_address_usage": "2019-08-24T14:15:22Z", "account_type": "not_applicable", "account_id": "string", "three_ds_requestor_authentication_info": { "three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred", "three_ds_req_auth_timestamp": "2019-08-24T14:15:22Z", "three_ds_req_auth_data": "string" } }, "merchant_risk_info": { "delivery_email": "brucewayne@email.com", "delivery_timeframe": "electronic_delivery", "is_preorder": true, "is_reorder": false, "shipping_indicator": "billing_address", "reorder_items_indicator": "first_time_ordered", "pre_order_purchase_indicator": "merchandise_available", "pre_order_date": "2019-08-24T14:15:22Z", "gift_card_amount": "123", "gift_card_currency": "USD", "gift_card_count": "02" }, "reference": "ORD-5023-4E89", "transaction_type": "goods_service", "next_actions": [ "redirect_cardholder" ], "ds": { "ds_id": "A000000003", "reference_number": "VISA.V 17 0003", "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c" }, "acs": { "reference_number": "ACSRefNum1234", "transaction_id": "be481bd1-1f1d-4ef8-9fa8-0fb2a38e3c87", "operator_id": "ACSRefNum1234", "url": "https://server.acsdomainname.com", "signed_content": "eyJ4NWMiOlsiTUlJQjdEQ0NBWktnQXdJQkFnSVZBSzIxWEc5SVBCL083QzZjUTBvRlJJUkIwWDI0TUFvR0NDcUdTTTQ5QkFNQ01INHhDekFKQm", "challenge_mandated": true, "authentication_type": "string", "challenge_cancel_reason": "cardholder_cancel", "interface": "native_ui", "ui_template": "text", "challenge_cancel_reason_code": "string" }, "response_code": "Y", "response_status_reason": "01", "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=", "eci": "05", "xid": "XSUErNftqkiTdlkpSk8p32GWOFA", "cardholder_info": "Card declined. Please contact your issuing bank.", "card": { "instrument_id": "src_ubfj2q76miwundwlk72vxt2i7q", "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q", "metadata": { "card_type": "CREDIT", "card_category": "CONSUMER", "issuer_name": "Checkout", "issuer_country": "GB", "product_id": "MDS", "product_type": "Debit MasterCard® Card" } }, "recurring": { "days_between_payments": 28, "expiry": "20220901" }, "installment": { "number_of_payments": 2, "days_between_payments": 28, "expiry": "20220901" }, "initial_transaction": { "acs_transaction_id": "stringstringstringstringstringstring", "authentication_method": "frictionless_authentication", "authentication_timestamp": "2023-02-06T15:00:00.000Z", "authentication_data": "string", "initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u" }, "customer_ip": "192.168.1.1", "_links": { "issuer_fingerprint": { "href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441/issuer-fingerprint" }, "collect_channel_data": { "href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441/collect-data" }, "three_ds_method_url": { "href": "https://api.hsbc.com/3dsmethod?tx=123456" }, "acs_url": { "href": "https://api.hsbc.com/challenge" }, "complete": { "href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441/complete" }, "success_url": { "href": "string" }, "failure_url": { "href": "string" }, "callback_url": { "href": "string" }, "self": { "href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441" } }, "authentication_date": "2019-08-24T14:15:22Z", "exemption": { "requested": "none", "applied": "none", "code": "string", "trusted_beneficiary": { "status": "Y", "source": "01" } }, "flow_type": "challenged", "challenge_indicator": "no_preference", "optimization": { "optimized": true, "framework": "acceptance_rates", "optimized_properties": [ { "field": "challenge_indicator", "original_value": "trusted_listing", "optimized_value": "transaction_risk_assessment" } ] }, "scheme_info": { "name": "cartes_bancaires", "score": "string", "avalgo": "string" }, "3ds": { "challenge_request": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjYwYTY2ZDRjLTdjY2EtNDc1Zi04YzMxLWFiMjkwNTI1M2M4NiIsImFjc1RyYW5zSUQiOiI1ODVhM2NlZi04OWQ4LTQ3ZDMtYjk4Yi0xMDhiMGRjYjEyYzEiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0", "interaction_counter": "03", "error_details": { "error_code": "101", "error_component": "D", "error_detail": "acctNumber", "error_description": "Cardholder Account Number is not in a range belonging to Issuer." } }, "preferred_experiences": { "google_spa": { "status": "available", "reason": [ "Invalid response" ] }, "3ds": { "status": "available", "reason": [ "Invalid response" ] } }, "experience": "3ds", "google_spa": { "token": { "number": "string", "expiry_month": 0, "expiry_year": 0 } } } ``` The response returns the [next actions](#Next_actions) and [session status](#Session_statuses). --- ## Calculate the issuer fingerprint > **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 `PUT` request to the `/issuer-fingerprint` endpoint. This returns the [next actions](#Next_actions) and [session status](#Session_statuses). If one of the next actions is `issuer_fingerprint`, the customer's browser must contact the issuer's ACS directly to calculate its fingerprint. ### Create a payload 1. Construct the following base64 encoded payload: ``` { "threeDSServerTransID": //The transaction_id property of the session, "threeDSMethodNotificationURL": //The URL to receive the 3DS method notification message } ``` 2. Send the payload to the `three_ds_method_url` property of the session's `_links` object using a `POST` request and putting the base64 encoded data in a `threeDSMethodData` form field. ### Redirect 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: ``` { "threeDSServerTransID": //the transaction_id property of the session } ``` 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: > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/sessions-interceptor/3ds-method-notification` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/sessions-interceptor/3ds-method-notification` ### Listen for completion After you `POST` the `threeDSMethodData`, you can be notified of completion by listening for a browser event as follows: ```js window.addEventListener('message', messageCallback, false); ``` `messageCallback` is a function that has the following signature: ```js function messageCallback(event) { console.log(event.data); } ``` `event.data` contains the following object: ``` { "threeDSServerTransID": //The session's transaction_id property } ``` ### Complete the fingerprint To update the `three_ds_method_completion` property, send a `PUT` 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`. --- ## Collect the channel data > **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](https://www.checkout.com/docs/developer-resources/sdks/3ds-sdks.md). 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](https://api-reference.checkout.com/tag/Standalone/#operation/updateSession) 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`. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `PUT` `https://{prefix}.api.checkout.com/sessions/{session_id}/collect-data` **Sandbox** `PUT` `https://{prefix}.api.sandbox.checkout.com/sessions/{session_id}/collect-data` In the request body, provide the following fields: **Browser authentication** | Field name | Description | | --- | --- | | `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 color 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). | **App authentication** | Field name | Description | | --- | --- | | `channel`

`required`

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

`string` | 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`

`required`

`integer` | Indicates the maximum amount of time (in minutes) for all exchanges. | | `sdk_ephem_pub_key`

`required`

`object` | 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`

`required`

`string` | Contains data encrypted by the SDK for the directory server to decrypt. | | `sdk_transaction_id`

`required`

`string` | Unique ID assigned by the SDK to identify a single transaction. | | `sdk_interface_type`

`required`

`string` | 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`

`required`

`array` | 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. | ### Response example ```json { "exemption": { "requested": "transaction_risk_assessment", "applied": "transaction_risk_assessment", "trusted_beneficiary": { "status": "Y", "source": "ACS" } } } ``` 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`, or `unavailable`. - The [next actions](#Next_actions) – This can be `challenge_cardholder` or `complete`. - The [session status](#Session_status) – If successful, the status is `processing`. If the authentication was started but could not be completed, it is `expired`. - `exemption` object – If the authentication request included a [3DS exemption](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure/standalone-sessions/3ds-exemptions.md) that was successfully applied. --- ## Handle the 3DS challenge > **Information** > > For browser channel only. > You can skip this step for app channel because Checkout.com's [mobile SDKs](https://www.checkout.com/docs/developer-resources/sdks/3ds-sdks.md) 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). #### Example session with challenge ```json { "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 a challenge request If `next_actions` contains `challenge_cardholder`, follow these steps: 1. 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. Set to the protocol_version property of the session, "challengeWindowSize": //The requested challenge size. See the following possible values } ``` 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. 2. Once the CReq message is constructed, base64 encode it and `POST` it to the session's `acs.url` property, in a `creq` form field. Ensure that the encoded CReq message does not contain any padding. ### Render the challenge If the CReq message is successful, the response returns the HTML needed to render the challenge. For example: ```html Checkout 3D Simulator
Simulator

3D-Secure 2 Authentication

Please enter your password

``` > **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. ### Listen for the outcome If you want to be notified about the completion of the challenge, you can register an event handler on your page as follows: ```js window.addEventListener('message', messageCallback, false); ``` `messageCallback` is a function that has the following signature: ```js function messageCallback(event) { console.log(event.data); } ``` `event.data` contains the following object: ```json { "transStatus": "Y", "threeDSServerTransID": "352455b7-b3b1-4696-a916-69e2e4274e6c" } ``` `threeDSServerTransID` is the `transaction_id`. `transStatus` is one of the following values: | Value | Description | | --- | --- | | `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) | 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. --- ## Complete the session > **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](https://api-reference.checkout.com/tag/Standalone/#operation/completeSession) endpoint, and provide the session ID as the `{session_id}` path parameter. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/sessions/{session_id}/complete` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/sessions/{session_id}/complete` ### Response 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. ### Example authentication outcome ```json { "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_status_reason": "01", "cryptogram": "MTIzNDU2Nzg5MDA5ODc2NTQzMjE=", "eci": "05", "challenged": true } ``` 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 | | --- | --- | | `session_id`

`string` | The unique identifier for the session. | | `amount`

`integer` | The amount in the [major currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md). | | `currency`

`string` | The payment currency.
Format – [ISO 4217 code](https://www.checkout.com/docs/developer-resources/testing/codes/currency-codes.md)
Example – `USD` | | `status`

`string` | The session's status.

This can be one of:

- `approved`
- `attempted`
- `challenge_abandoned`
- `declined`
- `expired`
- `rejected`
- `unavailable` | | `authentication_type`

`string` | The type of payment the session is for. | | `authentication_category`

`string (enum)` | The category of the authentication request.

This can be one of:

- `non-payment`
- `payment` | | `reference`

`string` | Your reference for the payment.
Format – Maximum 100 characters | | `approved`

`boolean` | Indicates whether the authentication was successful. | | `protocol_version`

`string` | The 3DS version used for authentication.

Possible values:

- `2.1.0`
- `2.2.0` | | `response_code`

`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:

- `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
- `I` – Informational only; 3DS requestor challenge preference acknowledged
- `N` – Not authenticated / account not verified; transaction denied
- `R` – Authentication / account verification rejected; issuer is rejecting authentication / verification and requests that the authorization not be attempted
- `U` – Authentication/ account verification could not be performed; technical or other problem, as indicated in ARes or RReq
- `Y` – Authentication verification successful | | `response_status_reason`

`string` | The response from the DS or ACS that provides information on why the `response_code` field has the specified value.

This can be one of:

- `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` | A payment system-specific value provided as part of the ACS registration for each supported DS. | | `eci`

`string` | The electronic commerce indicator (ECI). | | `challenged`

`boolean` | Indicates whether this session involved a challenge. |