Skip to content

Hosted sessions

Last updated: 20th July 2022

Hosted sessions are the simplest solution for authenticating transactions with 3D Secure.

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.

Hosted sessions are suitable for authentications initiated from browsers only.


Step 1: Request a session

To begin, make a session request.

Endpoints

For the full API specification, see the API reference.

    post

    https://api.checkout.com/sessions

    Additional parameters

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

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    {
    "source": {
    "type": "card",
    "number": "4485040371536584",
    "expiry_month": 1,
    "expiry_year": 2030
    },
    "amount": 100,
    "currency": "USD",
    "authentication_type": "regular",
    "authentication_category": "payment",
    "challenge_indicator": "no_preference",
    "reference": "ORD-5023-4E89",
    "transaction_type": "goods_service",
    "shipping_address": {
    "address_line1": "Checkout.com",
    "address_line2": "90 Tottenham Court Road",
    "city": "London",
    "state": "UK",
    "zip": "W1T 4TJ",
    "country": "GB"
    },
    "completion": {
    "type": "hosted",
    "success_url": "http://example.com/sessions/success",
    "failure_url": "http://example.com/sessions/fail"
    }
    }

    Response example

    You should receive a 202 - Accepted response with a _links.redirect link. For the full API specification, see the API reference.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    {
    "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"
    }
    }
    }

    Additional response fields

    Field nameDescription

    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.

    next_actions

    array

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

    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

    To increase the likelihood of a frictionless transaction, request an exemption in your API request. You can request an exemption for transactions that must be Strong Customer Authentication (SCA) compliant, provided it meets the listed possible exemptions.

    You are able to submit exemptions directly in the authorization stage of the payment flow if that is your preference.

    Exemptions are only supported by Visa and Mastercard. Exemptions requested by you may change based on what’s supported by the scheme.

    Liability shift

    If you request an exemption, and the customer’s bank approves it, you do not benefit from the liability shift. This means you would be liable if the transaction turned out to be fraudulent.

    You will need to opt in to use exemptions. Transaction Risk Assessment (TRA) is only applicable to merchants with low fraud rate. Contact your Customer Success Manager to enable this feature.

    ExemptionDescription

    low_value

    For payments where the amount does not exceed €30.

    SCA may still be requested by the issuer despite the payment satisfying the requirements for low_value exemption. This may be due to either:

    • The cumulative amount for transactions initiated by the cardholder since the last SCA authentication exceeds €100.
    • The consecutive number of payment transactions initiated by the cardholder since the last SCA authentication exceeds 5.

    secure_corporate_payment

    For payments that use secure corporate cards, which are exempt from 3D Secure authentication.

    trusted_listing

    For payments where the cardholder has already added the merchant as a trusted merchant.

    trusted_listing_prompt

    For payments where the merchant would like to bring up a prompt to allow the cardholder to add the merchant as a trusted merchant.

    This will request for a challenge, which will have a prompt to allow the cardholder to add the merchant as a trusted merchant.

    transaction_risk_assessment

    For payments that satisfy the authentication amount criteria set by Checkout.com.

    • €100 to €250 for Checkout.com UK acquirer
    • €250 to €500 for Checkout.com FR acquirer

    If the issuer rejects the exemption, they will request a challenge, which the cardholder is required to complete

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    {
    "source": {
    "type": "card",
    "number": "4485040371536584",
    "expiry_month": 1,
    "expiry_year": 2030
    },
    "amount": 100,
    "currency": "USD",
    "authentication_type": "regular",
    "authentication_category": "payment",
    "challenge_indicator": "low_value",
    "reference": "ORD-5023-4E89",
    "transaction_type": "goods_service",
    "shipping_address": {
    "address_line1": "Checkout.com",
    "address_line2": "90 Tottenham Court Road",
    "city": "London",
    "state": "UK",
    "zip": "W1T 4TJ",
    "country": "GB"
    },
    "completion": {
    "type": "non_hosted",
    "callback_url": "https://example.com/sessions/callback"
    }
    }

    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.

    Visa requirements

    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.

    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 authorisations. 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 authorisations are performed in the format YYYY/MM/DD. 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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    {
    "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": "Checkout.com",
    "address_line2": "90 Tottenham Court Road",
    "city": "London",
    "state": "UK",
    "zip": "W1T 4TJ",
    "country": "GB"
    },
    "completion": {
    "type": "hosted",
    "callback_url": "https://example.com/sessions/callback"
    }
    }

    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.

    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.

    StatusDescription

    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.

    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 typeActionDescriptionChannel

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