# Hosted sessions Hosted sessions are the simplest solution for authenticating transactions with 3D Secure (3DS). Start a session and then redirect the customer using the link in the response. We'll gather the necessary payment, device and cardholder data and take care of the rest. > **Information** > > Hosted sessions are suitable for authentications initiated from browsers only. --- ## How it works 1. Request a session 2. Redirect the customer --- ## Request a session Call the [Request a session](https://api-reference.checkout.com/tag/Standalone/#operation/createSession) 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` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/sessions` > **Information** > > To increase the likelihood of frictionless authentication, [add additional data fields](#Additional_authentication_data) when requesting a session. ### Request example ```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": "hosted", "success_url": "http://example.com/sessions/success", "failure_url": "https://example.com/payments/failure" } } ``` ### Response example You receive a `202 - Accepted` response with a `_links.redirect` link. For the full API specification, see the [API reference](https://api-reference.checkout.com/tag/Standalone/#operation/createSession). > **Information** > > If the card is not enrolled in 3DS with the selected scheme, you receive a `422` response and a `card_not_enrolled` error. > > > > If you want to continue to payment authorization, you can process the transaction as a non-3DS payment by setting `3ds.enabled` to `false` in the [payment request](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout). ```json { "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://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441" } } } ``` ### Additional response fields | 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 all possible statuses and their meanings](#Session_statuses). | | `next_actions`

`array` | Specifies what action to take to complete the session. For example: `redirect_cardholder`.

[See all possible actions and their meanings](#Next_actions). | | `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. | | `recurring`

`object` | Contains the recurring fields submitted in the request. | | `installment`

`object` | Contains the installment fields submitted in the request. | | `_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. | --- ## Exemptions Learn more about [exemptions](https://www.checkout.com/docs/risk-management/3d-secure/sessions/3ds-exemptions.md). --- ## Recurring and installment payments In regions where SCA is mandated, following the Payment Services Directive (PSD2) means the initial cardholder-initiated transaction (CIT) payment will require SCA. As such, you must authenticate the CIT with a challenge in these mandated regions. In your API request, set `authentication_type` to `recurring` or `installment`. You will also need to send the `recurring` or `installment` object with the following required fields. > **Information** > > For Visa payments, the initial customer-initiated transaction (CIT) to set up a recurring or installment series should be processed as a `regular` authentication and the additional fields described in the following fields are not required. | Field name | Description | | --- | --- | | `number_of_payments`

Only applies to `installment` payments. | Integer
Min : 1
Indicates the agreed total number of payment installments to be made in the duration of the installment agreement. | | `days_between_payments` | Integer
Default : 1
Indicates the minimum number of days between authorizations. If no value is specified for a recurring authentication type the default value will be used. | | `expiry` | String
Default : "99991231"
Date after which no further authorizations are performed, in the format `YYYYMMDD`. If no value is specified for a recurring authentication type the default value will be used. | For non-recurring or non-installment payments, these fields will be ignored if they are sent to the API. ### Request example ```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": "hosted", "callback_url": "https://example.com/sessions/callback" } } ``` --- ## 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, process the 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. > **Information** > > If the authentication is approved or attempted, the customer will be redirected to your success URL. All other authentication results will redirect the customer to your failure URL. ### Session properties ### 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 been authenticated by a stand-in service, because the access control server could not be reached or does not support 3DS2 natively. You can treat this as a successful authentication and proceed to authorization. | | `unavailable` | Authentication failed because of technical problems with the directory server or the issuer's access control server. | | `declined` | The transaction was not authenticated. The issuer denied the transaction. | | `rejected` | The transaction was rejected. The issuer is rejecting the authentication and requests that authorisation not be attempted. | | `challenged` | Authentication has been requested but the issuer requires that the cardholder be presented with a challenge. | | `challenge_abandoned` | Authentication has been started and challenged, but the cardholder did not complete the challenge. | | `expired` | Authentication has been started but the channel data could not be collected, meaning an authentication request was not created. | ### Next actions Below are the possible values for the `next_actions` field. When present, they identify what action to take in order to complete the session. | Session 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 | | 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. | | 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. | | 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. |