--- title: "Create a Hosted Payments Page session" method: POST path: "/hosted-payments" tags: ["Hosted Payments Page"] --- # Create a Hosted Payments Page session `POST /hosted-payments` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/hosted-payments` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a Hosted Payments Page session and pass through all the payment information, like the amount, currency, country and reference. To get started with our Hosted Payments Page, contact your solutions engineer or request support. ## Request body - HostedPaymentsRequest - `amount` integer: The payment amount. The exact format depends on the currency - `currency` string, required: The three-letter ISO currency code of the payment - `payment_type` 'Regular' | 'Recurring': This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order) - `authorization_type` 'Final' | 'Estimated': The authorization type. - `payment_plan` PaymentSessionPaymentPlanRecurring: The information to process a recurring payment request. To be used when the payment_type is Recurring. - `amount_variability` 'Fixed' | 'Variable': Specifies whether the amount is fixed or variable for each recurrence. - `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`). - `payment_ip` string, ipv4 - `billing_descriptor` object: An optional description that is displayed on the customer's statement identifying a purchase - `name` string, required: A dynamic description of the change - `city` string, required: The city from which the charge originated - `reference` string: The reference shown on the statement. Required for payouts to bank accounts. - `reference` string: A reference you can use to identify the payment. For example, an order number. - For Amex payments, this must be at most 30 characters. - For Benefit payments, the reference must be a unique alphanumeric value. - For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit. - `description` string: A description of the payment - `display_name` string: The merchant name to display to customers on the checkout page. - `processing_channel_id` string: The processing channel to be used for the payment - `amount_allocations` object[]: The sub-entities that the payment is being processed on behalf of - `id` string, required: The id of the sub-entity. - `amount` integer, required: The split amount - this will be credited to your sub-entity's currency account. The sum of all split amounts must be equal to the payment amount. The amount must be provided in the minor currency unit. - `reference` string: A reference you can later use to identify this split, such as an order number. - `commission` object: Commission you'd like to collect from this split - this will be credited to your currency account. The commission cannot exceed the split amount. Commission = (`amount` * `commission.percentage`) + `commission.amount` - `amount` integer: Optional fixed amount of commission to collect. The amount must be provided in the minor currency unit. - `percentage` number: Optional percentage of commission to collect. Supports up to 8 decimal places. - `customer` object: The customer's details - `email` string, email: The customer's email address. - `name` string: The customer's name. This will only set the name for new customers. - `phone` PaymentInterfacesPhoneNumber: A phone number - `country_code` string: The international country calling code. - `number` string: The phone number. - `summary` PaymentInterfacesCustomerSummary: Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara` - `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. - `is_premium_customer` boolean: Specifies whether the customer is a premium customer. - `is_returning_customer` boolean: Specifies whether the customer is a returning customer. - `lifetime_value` number, float: The customer's lifetime value. This is the total monetary amount that the customer has ordered, in their local currency, excluding the following: - canceled orders - rejected payments - refunded payments - Tamara payments The lifetime value is an indicator of how valuable the relationship with the customer is to your company. - `shipping` object: The address any products are being sent to. - `address` Address, required - `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`. - `billing` object, required: The billing details - `address` Address, required - `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`. - `recipient` PaymentInterfacesRecipient: Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions. - `dob` string, date: The recipient's date of birth, in the format `YYYY-MM-DD`. - `account_number` string: An identifier related to the primary recipient's account. For example, an IBAN, an internal account number, a phone number, or the first six and last four digits of the PAN. - `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. - `first_name` string: The recipient's first name. - `last_name` string: The recipient's last name. - `processing` PaymentInterfacesProcessing: Use the processing object to influence or override the data sent during card processing - `aft` boolean: Indicates whether the payment is an [Account Funding Transaction](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions) - `discount_amount` number: The discount amount applied to the transaction by the merchant. - `shipping_amount` number: The total freight or shipping and handling charges for the transaction. - `tax_amount` number: The customer's value-added tax registration number. - `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. - `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` union: Contains information about the passenger(s) on the flight. PayPal requires a single object. - PaymentInterfacesProcessingAirlinePassengerData[]: Array of passengers 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. - PaymentInterfacesProcessingAirlinePassengerData: Contains information about a passenger 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. - `order_id` string: The number provided by the cardholder. Purchase order or invoice number may be used. - `surcharge_amount` integer: Surcharge amount applied to the transaction in minor units by the merchant. - `duty_amount` number: The total charges for any import/export duty included in the transaction. - `shipping_tax_amount` number: The tax amount of the freight or shipping and handling charges for the transaction. - `affiliate_id` string: The unique identifier for Visa-registered ramp providers. Must only contain alphanumeric characters. If you're a Visa-registered ramp provider operating with affiliates, this field is required. - `affiliate_url` string: The affiliate URL. If you're a Visa-registered ramp provider operating with affiliates, this field is required. - `purchase_country` string: The purchase country of the customer. ISO 3166 alpha-2 purchase country. - `merchant_initiated_reason` 'Delayed_charge' | 'Resubmission' | 'No_show' | 'Reauthorization': Indicates the reason for a merchant-initiated payment request. - `campaign_id` integer: Unique number of the campaign this payment will be running in. Only required for Afterpay campaign invoices. - `original_order_amount` number: The payment for a merchant's order may be split, and the original order price indicates the transaction amount of the entire order. - `receipt_id` string: Merchant receipt ID. - `merchant_callback_url` string: A URL which you can use to notify the customer that the order has been created. - `line_of_business` string: Beta

The line of business that the payment is associated with. - `pan_preference` 'fpan' | 'dpan': Specifies the preferred type of Primary Account Number (PAN) for the payment: * DPAN: Uses the Checkout.com Network Token. * FPAN: Uses the full card number. **Note**: This only works when `source.type` is any of: - `cards` - `instruments` - `tokens` - `provision_network_token` boolean: Indicates whether to provision a network token for the payment. - `reconciliation_id` string: Transaction identifier used to track a payment request - `aggregator` PaymentInterfacesProcessingAggregator: Contains information about the payment aggregator. - `sub_merchant_id` string: ID that you assigned to the sub-entity. - `aggregator_id_visa` string: Visa identifier of the payment aggregator. - `aggregator_id_mc` string: Mastercard identifier of the payment aggregator. - `allow_payment_methods` 'alipay_cn' | 'alipay_hk' | 'alma' | 'applepay' | 'bancontact' | 'benefit' | 'bizum' | 'card' | 'dana' | 'eps' | 'gcash' | 'googlepay' | 'ideal' | 'kakaopay' | 'klarna' | 'knet' | 'mbway' | 'mobilepay' | 'multibanco' | 'octopus' | 'p24' | 'paynow' | 'paypal' | 'plaid' | 'qpay' | 'sepa' | 'stcpay' | 'stored_card' | 'tabby' | 'tamara' | 'tng' | 'truemoney' | 'twint' | 'vipps' | 'wechatpay' - `disabled_payment_methods` PaymentInterfacesPaymentMethodEnum[] - `products` object[]: Contains details about the products in the order. - `reference` string: The item reference or product stock keeping unit (SKU). - `url` string: Link to the line item's product page. - `name` string, required: The descriptive name of the line item. - `quantity` integer, required: The number of line items. - `price` integer, required: The price per item in minor units, including tax but excluding discounts. The exact format depends on the currency. See Calculating the amount. - `risk` object: Configures the risk assessment performed during payment processing. - `enabled` boolean, required: Specifies whether to perform a risk assessment. - `customer_retry` object: Configures the parameters for customer retries. A customer retry is a payment attempt performed by the customer on the checkout page. This differs from [authorization request retries](https://api-reference.checkout.com/#operation/requestAPaymentOrPayout!path=0/retry&t=request) performed in the back end by Checkout.com. - `max_attempts` integer: The maximum number of customer retry attempts, excluding the initial payment attempt. - `sender` PaymentInterfacesSender: The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument. - `success_url` string, uri, required: For redirect payment methods, this overrides the default success redirect URL configured on your account - `cancel_url` string, uri, required: The URL to which the customer should be directed if they cancel the payment - `failure_url` string, uri, required: For redirect payment methods, this overrides the default failure redirect URL configured on your account - `metadata` object: Allows you to store additional information about the transaction. This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays. - `locale` 'ar' | 'da-DK' | 'de-DE' | 'el' | 'en-GB' | 'es-ES' | 'fi-FI' | 'fil-PH' | 'fr-FR' | 'hi-IN' | 'id-ID' | 'it-IT' | 'ja-JP' | 'ms-MY' | 'nb-NO' | 'nl-NL' | 'pt-PT' | 'sv-SE' | 'th-TH' | 'vi-VN' | 'zh-CN' | 'zh-HK' | 'zh-TW': Creates a translated version of the page in the specified language - `3ds` object: Information required for 3D Secure payments - `enabled` boolean: Whether to process this payment as a 3D Secure payment - `attempt_n3d` boolean: Applies only when `3ds.enabled` is set to `true`. Set to `true` to attempt the payment without 3DS when the issuer, card, or network doesn’t support 3DS. - `challenge_indicator` 'no_preference' | 'no_challenge_requested' | 'challenge_requested' | 'challenge_requested_mandate': Indicates the preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether or not the customer receives the challenge. - `allow_upgrade` boolean: Whether to process this payment as 3D Secure if the authorization was soft declined because 3DS authentication is required. - `exemption` 'low_value' | 'secure_corporate_payment' | 'trusted_listing' | 'transaction_risk_assessment' | '3ds_outage' | 'sca_delegation' | 'out_of_sca_scope' | 'other' | 'low_risk_program' | 'recurring_operation': Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide. - `capture` boolean: Whether to capture the payment (if applicable). - `capture_on` string, date-time: ISO 8601 timestamp - `instruction` object: Details about the payment instruction. - `purpose` 'donations' | 'education' | 'emergency_need' | 'expatriation' | 'family_support' | 'financial_services' | 'gifts' | 'income' | 'insurance' | 'investment' | 'it_services' | 'leisure' | 'loan_payment' | 'medical_treatment' | 'other' | 'pension' | 'royalties' | 'savings' | 'travel_and_tourism': The purpose of the payment. This field might be required for AFT transactions depending on the card's `issuer_country`. To view a card's `issuer_country`, [retrieve the card's metadata](https://api-reference.checkout.com/#operation/requestCardMetadata!c=200&path=issuer_country&t=response). See the [AFT documentation page](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction) for more details. - `payment_method_configuration` object: Configuration options for specific payment methods. - `applepay` object: Configuration options specific to Apple Pay payments. - `account_holder` object: The account holder's details. - `type` string, required - `store_payment_details` 'disabled' | 'enabled': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled`, you must: - have obtained consent from the cardholder to store their payment details - provide a customer ID or email address in the request If the request's `payment_type` is set to one of the following values, you do not need to provide this field: - `Installment` - `Recurring` - `Unscheduled` - `card` object: Configuration options specific to card payments. - `store_payment_details` 'disabled' | 'enabled' | 'collect_consent': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled` or `collect_consent`, you must: - Have obtained consent from the cardholder to store their payment details - Provide `customer.id` or `customer.email` in the request You do not need to provide this field if `payment_type` is set to one of the following values: - `Installment` - `Recurring` - `Unscheduled` - `account_holder` object: The account holder's details. - `type` string, required - `googlepay` object: Configuration options specific to Google Pay payments. - `account_holder` object: The account holder's details. - `type` string, required - `store_payment_details` 'disabled' | 'enabled': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled`, you must: - have obtained consent from the cardholder to store their payment details - provide a customer ID or email address in the request If the request's `payment_type` is set to one of the following values, you do not need to provide this field: - `Installment` - `Recurring` - `Unscheduled` - `stored_card` object: Configuration options specific to stored card payments. - `customer_id` string: The unique identifier for an existing [customer](https://api-reference.checkout.com/#tag/Customers). Enables the stored card payment method if the associated customer has one or more payment instruments stored. This value takes precedence over `payment_method_configuration.stored_card.instrument_ids` when determining the stored cards to present to the customer. - `instrument_ids` string[]: The unique identifiers for card Instruments. Enables stored card payment method if any one of them exists. The first valid payment instrument in the list will be presented to the customer as the default option. Alternatively, you can explicitly specify a default payment instrument by providing its ID in the `payment_method_configuration.stored_card.default_instrument_id` field. - `default_instrument_id` string: The unique identifier for the payment instrument to present to the customer as the default option. ## Response `201` Created Hosted Payments Page - HostedPaymentsResponse - `id` string, required: The unique identifier for a Hosted Payments Page. - `reference` string: A reference you can later use to identify this payment, such as an order number. - `warnings` object[]: Related to the `allow_payment_methods` object in the request. Included in the response if an alternative payment method is passed through, but no card schemes are configured against the account. - `code` string: The reason for the warning - `description` string: The description of the warning code - `value` 'card' | 'sofort' | 'ideal' | 'knet' | 'bancontact' | 'eps' | 'p24' | 'multibanco': Payment method for which the warning applies - `_links` object, required: The links related to the hosted payment. - `self` Link - `href` string, required: The link URL - `redirect` Link - `href` string, required: The link URL ## Other responses - `401`: Unauthorized - `422`: Invalid data was sent --- [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)