Request a session

​

Create a payment session to authenticate a cardholder before requesting a payment. Payment sessions can be linked to one or more payments (in the case of recurring and other merchant-initiated payments).

The next_actions object in the response tells you which actions can be performed next.

Body·
application/json
  • source
    required

    The source of the authentication.

    The source of the authentication.

    • type
      Discriminator
      Type: string
      required

      The payment source type

    • number
      Type: string
      min length:  
      13
      max length:  
      19
      required

      The card number.

    • expiry_month
      Type: integer
      min:  
      1
      max:  
      12
      required

      The expiry month of the card.

    • expiry_year
      Type: integer
      required

      The expiry year of the card.

    • scheme
      Type: string enum

      Indicates the cardholder scheme choice

      values
      • amex
      • cartes_bancaires
      • diners
      • mastercard
      • visa
      • discover
      • upi
      • jcb
    • billing_address
      Type: object ·

      The customer's billing address. Any special characters will be replaced.

    • home_phone
      Type: object ·

      The cardholder's home phone number

    • mobile_phone
      Type: object ·

      The cardholder's mobile phone number

    • work_phone
      Type: object ·

      The cardholder's work phone number

    • email
      Type: string
      max length:  
      254

      The email of the cardholder

    • name
      Type: string
      min length:  
      2
      max length:  
      45

      The name of the cardholder. Any special characters will be replaced.

    • stored
      Type: boolean

      Indicates whether this card is being submitted from your own stored card-on-file system, rather than being entered by the customer at the time of payment. Set to true when you provide card details that you already have on file for the customer.

  • currency
    Type: string
    min length:  
    3
    max length:  
    3
    required

    The three-letter ISO currency code

  • completion
    required

    The redirect information needed for callbacks or redirects after the payment is completed

    The redirect information needed for callbacks or redirects after the payment is completed

    • type
      Discriminator
      max length:  
      10      enum
      const:  
      hosted
      required

      Whether the session should be hosted by Checkout.com.

      values
      • hosted
    • success_url
      Type: string
      max length:  
      256      Format: uri
      required

      For hosted sessions, this overrides the default success redirect URL configured on your account

    • failure_url
      Type: string
      max length:  
      256      Format: uri
      required

      For hosted sessions, this overrides the default failure redirect URL configured on your account

  • amount
    Type: integer
    min:  
    0

    The payment amount in the minor currency unit.

    For recurring and installment payment types, this value is required and must be greater than zero.

    Omitting this value will set authentication_category to non_payment.

  • processing_channel_id
    Type: string Pattern: ^(pc)_(\w{26})$

    The processing channel to be used for the session. Required if this was not set in the request for the OAuth token.

  • marketplace
    Type: object ·

    Information related to authentication for payfac payments

  • authentication_type
    Type: string · enum

    Indicates the type of payment this session is for. Please note the spelling of installment consists of two ls.

    values
    • regular
    • recurring
    • installment
    • maintain_card
    • add_card
  • authentication_category
    Type: string · enum

    Indicates the category of the authentication request

    values
    • payment
    • non_payment
  • account_info
    Type: object ·

    Additional information about the Cardholder's account.

  • challenge_indicator
    Type: string ·
    max length:  
    50    enum

    Indicates whether a challenge is requested for this session.

    The following are requests for exemption:
    • low_value
    • trusted_listing
    • trusted_listing_prompt
    • transaction_risk_assessment

    If an exemption cannot be applied, then the value no_challenge_requested will be used instead.

    values
    • no_preference
    • no_challenge_requested
    • challenge_requested
    • challenge_requested_mandate
    • low_value
    • trusted_listing
    • trusted_listing_prompt
    • transaction_risk_assessment
    • data_share
  • billing_descriptor
    Type: object ·

    An optional dynamic billing descriptor.

  • reference
    Type: string ·
    max length:  
    100

    A reference you can later use to identify this payment, such as an order number. Do not pass sensitive information in this field e.g. card details

Responses
  • application/json
  • application/json
  • 401

    Unauthorized

  • application/json
  • application/json
  • application/json
Request Example for post/sessions
curl 'https://{prefix}.api.sandbox.checkout.com/sessions' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "source": {
    "type": "card",
    "scheme": "amex",
    "number": "4242424242424242",
    "expiry_month": 12,
    "expiry_year": 2077,
    "billing_address": {
      "address_line1": "123 High St.",
      "address_line2": "ABC building",
      "address_line3": "14 Wells Mews",
      "city": "London",
      "state": "ENG",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "home_phone": {
      "country_code": "234",
      "number": "0204567895"
    },
    "mobile_phone": {
      "country_code": "234",
      "number": "0204567895"
    },
    "work_phone": {
      "country_code": "234",
      "number": "0204567895"
    },
    "email": "bruce.wayne@email.com",
    "name": "Bruce Wayne",
    "stored": true
  },
  "amount": 6540,
  "currency": "USD",
  "processing_channel_id": "",
  "marketplace": {
    "sub_entity_id": "ent_rgyzti4x74xubmu72m6r3pvksa"
  },
  "authentication_type": "regular",
  "authentication_category": "payment",
  "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,
    "cardholder_account_age_indicator": "no_account,",
    "account_change": "",
    "account_change_indicator": "this_transaction",
    "account_date": "",
    "account_password_change": "",
    "account_password_change_indicator": "no_change",
    "transactions_per_year": 2,
    "payment_account_age": "",
    "shipping_address_usage": "",
    "account_type": "not_applicable",
    "account_id": "",
    "three_ds_requestor_authentication_info": {
      "three_ds_req_auth_method": "no_threeds_requestor_authentication_occurred",
      "three_ds_req_auth_timestamp": "",
      "three_ds_req_auth_data": ""
    }
  },
  "challenge_indicator": "no_preference",
  "billing_descriptor": {
    "name": "SUPERHEROES.COM"
  },
  "reference": "ORD-5023-4E89",
  "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": "",
    "gift_card_amount": "123",
    "gift_card_currency": "USD",
    "gift_card_count": "02"
  },
  "transaction_type": "goods_service",
  "shipping_address": {
    "address_line1": "123 High St.",
    "address_line2": "ABC building",
    "address_line3": "14 Wells Mews",
    "city": "London",
    "state": "ENG",
    "zip": "SW1A 1AA",
    "country": "GB"
  },
  "shipping_address_matches_billing": false,
  "completion": {
    "type": "non_hosted",
    "callback_url": "https://merchant.com/callback"
  },
  "channel_data": {
    "channel": "browser",
    "accept_header": "Accept:  *.*, q=0.1",
    "java_enabled": true,
    "javascript_enabled": true,
    "language": "FR-fr",
    "color_depth": "16",
    "screen_height": "1080",
    "screen_width": "1920",
    "timezone": "60",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "three_ds_method_completion": "Y",
    "ip_address": "1.12.123.255",
    "iframe_payment_allowed": true,
    "user_agent_client_hint": "Sec-CH-UA: \" Not A;Brand\";v=\"99\", \"Chromium\";v=\"96\", \"Google Chrome\";v=\"96\""
  },
  "recurring": {
    "days_between_payments": 28,
    "expiry": "20220901"
  },
  "installment": {
    "number_of_payments": 2,
    "days_between_payments": 28,
    "expiry": "20220901"
  },
  "optimization": {
    "framework": "acceptance_rates"
  },
  "initial_transaction": {
    "acs_transaction_id": "",
    "authentication_method": "frictionless_authentication",
    "authentication_timestamp": "2023-02-06T15:00:00.000Z",
    "authentication_data": "",
    "initial_session_id": "sid_p6prbhogijnuxgv4grm3ber55u"
  },
  "google_spa": {
    "continue_url": ""
  },
  "preferred_experiences": [
    "3ds"
  ],
  "device_information": {
    "device_id": "",
    "device_session_id": "dsid_ipsmclhxwq72phhr32iwfvrflm"
  }
}'

{
  "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,
    "cardholder_account_age_indicator": "no_account,",
    "account_change": "2026-09-23T13:52:07.856Z",
    "account_change_indicator": "this_transaction",
    "account_date": "2026-09-23T13:52:07.856Z",
    "account_password_change": "2026-09-23T13:52:07.856Z",
    "account_password_change_indicator": "no_change",
    "transactions_per_year": 2,
    "payment_account_age": "2026-09-23T13:52:07.856Z",
    "shipping_address_usage": "2026-09-23T13:52:07.856Z",
    "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": "2026-09-23T13:52:07.856Z",
      "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": "2026-09-23T13:52:07.856Z",
    "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": "string",
    "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_y3oqhf46pyzuxjbcn2gia/issuer-fingerprint"
    },
    "collect_channel_data": {
      "href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2gia/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_y3oqhf46pyzuxjbcn2gia/complete"
    },
    "success_url": {
      "href": "string"
    },
    "failure_url": {
      "href": "string"
    },
    "callback_url": {
      "href": "string"
    }
  },
  "authentication_date": "2026-09-23T13:52:07.856Z",
  "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": 1,
      "expiry_year": 1
    }
  }
}

Session processed successfully