--- title: "Request a Payment Context" method: POST path: "/payment-contexts" tags: ["Payment Context"] --- # Request a Payment Context `POST /payment-contexts` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/payment-contexts` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `string` scopes: `gateway`, `gateway:payment-contexts` - API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Send a Payment Context request.

Note: Successful Payment Context requests will always return a 201 response. Effective August 2026, Payment Context is no longer supported for new integrations. New integration requests return a `405 Method Not Allowed` response. For new integrations, call the [Create a Payment Setup](https://api-reference.checkout.com/tag/Payment-Setups#operation/createAPaymentSetup) endpoint instead. ## Headers - `Cko-Idempotency-Key` string ## Request body - PaymentContext - `source` union, required: The source of the payment. - object: Klarna Source - `type` string, required: The source type of the payment context request. - `account_holder` object, required - `billing_address` object, required - `country` string, required: The billing country or purchase country of the customer. The two-letter ISO country code of the address - object: PayPal Source - `type` string, required: The source type of the payment context request. - object: StcPay Source - `type` string, required: The source type of the payment context request. - object: PayPal Source - `type` string, required: The source type of the payment context request. - `amount` integer, required: The Payment Context Payment amount. The amount must be provided in the minor currency unit. - `currency` string, required: The three-letter ISO currency code. - `payment_type` 'Regular' | 'Recurring': "Recurring" must be specified if the payment is paid in multiple installments. - `capture` boolean: Whether to capture the later payment (if applicable). - `customer` PaymentContextDetailsCustomer: The customer details.
Required if `source.type` is `StcPay` or `Tabby`. - `phone` object: The customer's phone number.
Required if `source.type` is `StcPay` or `Tabby`. - `country_code` string: The international country calling code.
Required if `source.type` is `StcPay`. - `number` string: The phone number.
Required if `source.type` is `StcPay` or `Tabby`. - `phone_verified` boolean: Indicates if the phone number has been verified. - `email` string, email: The customer's email address.
Required if `source.type` is `Tabby`. - `name` string: The customer's full name.
Required if `source.type` is `Tabby`. - `email_verified` boolean: Indicates if the email address has been verified. - `summary` object: Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tabby` - `registration_date` string, date: The date the customer registered. - `first_transaction_date` string, date: The date of the customer's first transaction. - `last_payment_date` string, date: The date of the customer's last payment. - `total_order_count` integer: The total number of orders made by the customer. - `last_payment_amount` number, float: The amount of the customer's last payment. - `shipping` Shipping: The shipping details. - `first_name` string: The first name of the person receiving the goods or the service. - `last_name` string: The last name of the person receiving the goods or the service. - `email` string: The email address associated with the shipping order. - `address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `from_address_zip` string: The postal code or zip code of the location being shipped from. - `timeframe` 'ElectronicDelivery' | 'SameDay' | 'Overnight' | 'TwoDayOrMore': Indicates the merchandise delivery timeframe. The following values will be supported by Checkout.com, otherwise your specific value will be passed through to the provider. - `method` 'Digital' | 'PickUp' | 'BillingAddress' | 'OtherAddress': Indicates the shipping method chosen for the transaction. The following values will be supported by Checkout.com, otherwise your specific value will be passed through to the provider. - `delay` integer: The number of days by which the shipping is delayed. - `processing` PaymentContextProcessing: Use the processing object to influence or override the data sent during card processing. - `plan` object: The plan details for a recurring payment with PayPal. This is required when `payment_type: "recurring"`. - `type` 'MERCHANT_INITIATED_BILLING' | 'MERCHANT_INITIATED_BILLING_SINGLE_AGREEMENT' | 'CHANNEL_INITIATED_BILLING' | 'CHANNEL_INITIATED_BILLING_SINGLE_AGREEMENT' | 'RECURRING_PAYMENTS' | 'PRE_APPROVED_PAYMENTS', required: Type of payment plan. - `skip_shipping_address` boolean, required - `immutable_shipping_address` boolean, required - `discount_amount` number: The discount amount the merchant applied to the transaction. - `shipping_amount` number: The total freight or shipping and handling charges for the transaction. - `tax_amount` number: The total tax amount for the transaction, in [minor currency units](https://www.checkout.com/docs/payments/accept-payments/calculating-the-amount). - `invoice_id` string: Invoice ID number. - `brand_name` string: The label that overrides the business name in the PayPal account on the PayPal pages. - `locale` string: The language and region of the customer in ISO 639-2 language code; value consists of language-country. - `shipping_preference` 'no_shipping' | 'set_provided_address' | 'get_from_file': Shipping preference. - `user_action` 'pay_now' | 'continue': Property required by PayPal to have an appropriate payment flow. - `partner_customer_risk_data` object: An array of key-and-value pairs with merchant-specific data for the transaction. - `key` string: The key for the pair. - `value` string: The value for the pair. - `custom_payment_method_ids` string[]: Promo codes - An array that can be used to define which of the configured payment options within a payment category (pay_later, pay_over_time, etc.) should be shown for this purchase. - `airline_data` object[]: Contains information about the airline ticket and flights booked by the customer. - `ticket` object: Contains information about the airline ticket. - `number` string: The ticket's unique identifier. - `issue_date` string, date: Date the airline ticket was issued. - `issuing_carrier_code` string: Carrier code of the ticket issuer. - `travel_package_indicator` string: C = Car rental reservation, A = Airline flight reservation, B = Both car rental and airline flight reservations included, N = Unknown. - `travel_agency_name` string: The name of the travel agency. - `travel_agency_code` string: The unique identifier from IATA or ARC for the travel agency that issues the ticket. - `passenger` object[]: Contains information about the passenger(s) on the flight. - `first_name` string: The passenger's first name. - `last_name` string: The passenger's last name. - `date_of_birth` string, date: The passenger's date of birth. - `address` object: Contains information about the passenger's address. - `country` string: The two-letter ISO country code of the passenger's country residence. - `flight_leg_details` object[]: Contains information about the flight leg(s) booked by the customer. - `flight_number` string: The flight identifier. - `carrier_code` string: The IATA 2-letter accounting code (PAX) that identifies the carrier. This field is required if the airline data includes leg details. - `class_of_travelling` string: A one-letter travel class identifier. The following are common: F = First class, J = Business class, Y = Economy class, W = Premium economy. - `departure_airport` string: The IATA three-letter airport code of the departure airport. This field is required if the airline data includes leg details. - `departure_date` string, date: The date of the scheduled take off. - `departure_time` string: The time of the scheduled take off. - `arrival_airport` string: The IATA 3-letter airport code of the destination airport. This field is required if the airline data includes leg details. - `stop_over_code` string: A one-letter code that indicates whether the passenger is entitled to make a stopover. Can be a space, O if the passenger is entitled to make a stopover, or X if they are not. - `fare_basis_code` string: The fare basis code, alphanumeric. - `accommodation_data` object[]: Contains information about the accommodation booked by the customer. - `name` string: For lodging, contains the lodging name that appears on the storefront/customer receipts. For cruise, contains the ship name booked for the cruise. - `booking_reference` string: A unique identifier for the booking. - `check_in_date` string, date: For lodging, contains the actual or scheduled date the guest checked-in. For cruise, contains the cruise departure date also known as sail date. - `check_out_date` string, date: For lodging, contains the actual or scheduled date the guest checked-out. For cruise, contains the cruise return date also known as sail end date. - `address` object: The address details of the accommodation. - `address_line1` string: The first line of the address. - `zip` string: The postal code for the address. - `state` string: The state or province of the address country (ISO 3166-2 code of up to two alphanumeric characters). - `country` string: The ISO country code of the address. - `city` string: The address city. - `number_of_rooms` integer: The total number of rooms booked for the accommodation. - `guests` object[]: Contains information about the guests staying at the accommodation. - `first_name` string: The first name of the guest. - `last_name` string: The last name of the guest. - `date_of_birth` string, date: The date of birth of the guest. - `room` object[]: Contains information about the rooms booked by the customer. - `rate` string: For lodging, contains the nightly rate for one room. For cruise, contains the total cost of the cruise. - `number_of_nights_at_room_rate` string: For lodging, contains the number of nights charged at the rate provided in the rate field. For cruise, contains the length of the cruise in days. - `property_phone` object[]: The property's phone information. - `country_code` string: The property's phone country code. - `number` string: The property's phone number. - `customer_service_phone` object[]: The customer service phone information. - `country_code` string: The customer service phone country code. - `number` string: The customer service phone number. - `processing_channel_id` string: The processing channel to be used for the payment. - `reference` string: A reference you can later use to identify this Payment Context, such as an order number.
Can only be alphanumeric and must be unique for Benefit.
For Amex, the string limit is 30 characters. - `description` string: A description of the Payment Context. - `success_url` string, uri: For redirect payment methods, this overrides the default success redirect URL configured on your account. - `failure_url` string, uri: For redirect payment methods, this overrides the default failure redirect URL configured on your account. - `items` object[]: The order's line items.

Required for Klarna payments. - `type` string: The item type. For example, `physical`, `digital`. - `name` string: The descriptive name of the line item. - `quantity` integer: The number of line items. - `unit_price` integer: The unit price of the item in minor currency unit. - `reference` string: The item reference or product SKU (stock-keeping unit). - `total_amount` number: The total cost of the line item (including any tax and discount amount) in minor currency unit. Value = (quantity x unit_price) - discount_amount. - `tax_rate` number: The tax rate of the item line in minor units. The percentage value is represented with two implicit decimals. For example, 2000=20%. - `tax_amount` number: The total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase. - `discount_amount` number: The discount applied to each invoice line item. - `url` string: Link to the line item's product page. - `image_url` string: Link to the line item's product page. - `metadata` object: A set of key-value pairs store additional information about a transaction. You can send custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type - `string` - `number` - `boolean` Arrays and objects are not supported. You can provide up to 20 metadata fields per API call, but the value of each field must not exceed 255 characters in length. You can also reference [`metadata` properties](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection#Metadata) in your custom rules for Fraud Detection. ## Response `201` Payment Context Created. - PaymentContextResponse - `id` string, required: Payment Context's unique identifier. - `amount` integer: The payment amount. - `processed_on` string, date-time, required: Read-only UTC timestamp, automatically assigned by us - `status` string: The status of the payment context. - `response_code` string: The gateway response code. - `response_summary` string: The gateway response summary. - `available_payment_types` object[]: Contains information about the available payment type returned by the partner for this purchase. - `payment_type` 'Regular' | 'PayLater' | 'Installment': The available payment type returned by the partner for this purchase. - `payment_plan` PaymentPlan: The details of a recurring subscription or installment `payment_plan`. - `days_between_payments` integer: Indicates the minimum number of days between payments - `total_number_of_payments` integer: Indicates the agreed total number of payments - `current_payment_number` integer: The number of the current installment payment - `expiry` string: The date after which no further payments will be performed in the format YYYYMMDD - `name` string: The name of the payment plan. Required when `source.type` is `blik`. For Blik merchant-initiated requests using an external `partner_agreement_id`, this value is used as the Blik Alias Label. - `start_date` string: The date on which the first payment will be taken, in `YYYYMMDD` format. Required when `source.type` is `blik` and the recurring agreement is created without an initial payment (`amount` set to `0`). - `amount` integer: The amount to charge for each payment in the plan, in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount). Required when `source.type` is `blik`, `payment_plan.amount_variability` is `Fixed`, and the recurring agreement is created without an initial payment (`amount` set to `0`). - `unavailable_payment_types` object[]: Contains information about the unavailable payment type returned by the partner for this purchase. - `payment_type` 'Regular' | 'PayLater' | 'Installment': The unavailable payment type returned by the partner for this purchase. - `rejection_reason` string: The reason why the payment type is unavailable. - `payment_plan` PaymentPlan: The details of a recurring subscription or installment `payment_plan`. - `days_between_payments` integer: Indicates the minimum number of days between payments - `total_number_of_payments` integer: Indicates the agreed total number of payments - `current_payment_number` integer: The number of the current installment payment - `expiry` string: The date after which no further payments will be performed in the format YYYYMMDD - `name` string: The name of the payment plan. Required when `source.type` is `blik`. For Blik merchant-initiated requests using an external `partner_agreement_id`, this value is used as the Blik Alias Label. - `start_date` string: The date on which the first payment will be taken, in `YYYYMMDD` format. Required when `source.type` is `blik` and the recurring agreement is created without an initial payment (`amount` set to `0`). - `amount` integer: The amount to charge for each payment in the plan, in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount). Required when `source.type` is `blik`, `payment_plan.amount_variability` is `Fixed`, and the recurring agreement is created without an initial payment (`amount` set to `0`). - `description` string - `partner_metadata` PartnerMetadata, required: Processing object - `order_id` string: Order id - `customer_id` string: Customer id - `session_id` string: The unique identifier for the session created. - `client_token` string: The client token to pass to the client when initializing the JavaScript SDK. - `_links` object, required: The links related to the payment. - `self` Link - `href` string, required: The link URL ## Other responses - `401`: Unauthorized - `405`: Method Not Allowed. Not supported for creating new integrations on this resource. - `422`: Invalid data was sent. - `429`: Too many requests or duplicate request detected. - `502`: Bad gateway --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)