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

Note: successful payout requests will always return a 202 response. ## Headers - `Cko-Idempotency-Key` string - `Cko-Encryption-Key-Id` string - `Cko-Encrypted-Properties` string ## Request body - union - PaymentRequest - `source` union: The source of the payment. You can encrypt this field by using the `Cko-Encryption-Key-Id` and `Cko-Encrypted-Properties` [headers](https://api-reference.checkout.com/tag/payments/POST/payments.headers.Cko-Encryption-Key-Id). - object: A card payment source - `number` string, required: The card number (without separators). You can encrypt this field by using the `Cko-Encryption-Key-Id` and `Cko-Encrypted-Properties` [headers](https://api-reference.checkout.com/tag/payments/POST/payments.headers.Cko-Encryption-Key-Id). - `expiry_month` integer, required: The expiry month of the card - `expiry_year` integer, required: 4-digit expiry year of the card - `name` string: The name of the cardholder - `cvv` string: The card verification value/code. 3 digits, except for American Express (4 digits) - `stored` 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. - `store_for_future_use` boolean: This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response. - `billing_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`. - `account_holder` object: Information about the account holder of the card - `type` string, required - `allow_update` boolean: Specifies whether to use the Real-Time Account Updater to update the card information. - `type` 'card', required: The payment source type. - object - `billing_address` object - `address_line1` string: The first line of the address - `address_line2` string: The second line of the address - `city` string: The address city - `state` string: The address state - `zip` number: The address zip/postal code - `country` string: The two-letter ISO country code of the address - `type` 'wechatpay', required: The payment source type. - object: Vipps Request Source - `type` 'vipps', required: The payment source type. - object: Twint Request Source - `type` 'twint', required: The payment source type. - object: A Tamara payment source - `billing_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. - `type` 'tamara', required: The payment source type. - object: STC Pay request source - `type` 'stcpay', required: The payment source type. - object: SEPA DD Source - `country` string, required: The account's country, as an ISO 3166-1 alpha-2 code. - `account_number` string, required: The account holder's IBAN. - `currency` string, required: The account holder's account currency. - `mandate_id` string: The ID of the mandate. - `mandate_type` 'Core' | 'B2B': The type of mandate. - `date_of_signature` string: The date the mandate was signed, in the format yyyy-MM-dd - `account_holder` object, required: The account holder's personal information. - `first_name` string: The account holder's first name. - `last_name` string: The account holder's last name. - `company_name` string: The account holder's company name. - `type` 'Individual' | 'Corporate': The type of account holder - `billing_address` object, required: The account holder's billing address. - `address_line1` string, required: The account holder's street name. - `address_line2` string, required: The account holder's street number. - `city` string, required: The account holder's city. - `zip` string, required: The account holder's zip code. - `country` string, required: The account holder's country, as an ISO 3166-1 alpha-2 code. - `type` 'sepa', required: The payment source type. - object: Bacs Direct Debit Source - `type` 'bacs', required: The payment source type. - `id` string, required: The Bacs Direct Debit instrument ID. - object: A seQura payment source - `type` 'sequra', required: The payment source type. - `billing_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. - object: QPay Source - `type` 'qpay', required: The payment source type. - `quantity` integer: A numeric value greater than zero that represents the quantity of a purchased item. The value is used for display purposes only and does not affect the total amount of the payment. The minimum allowed value is 1. - `description` string, required: Alphanumeric string containing a description of the payment order. Note: The maximum allowed length of this property is 255 characters after UTF-8 URL encoding. - `language` string: Alphabetic value representing the language of the interface displayed to customer at merchant site, and used as language for the payment description parameter. PG will use this value to display the interface supporting selected language to the customer during the payment process. Supported values are: `En`, `Ar`. The default value is `En`. - `national_id` string: Alphanumeric value representing the national ID of the customer performing the transaction. The maximum allowed length of this property is 32. - object: P24 Source - `type` 'p24', required: The payment source type. - `payment_country` 'PL', required: The 2-letter ISO country code of the country in which the payment instrument is issued/operated. - `account_holder_name` string, required: The account holder. - `account_holder_email` string, required: RFC-compliant email address of the account holder. - `billing_descriptor` string: Payment billing descriptor. - object: A Plaid source. - `token` string, required: The `processor_token` returned from Plaid’s `/processor/token/create` endpoint. In the sandbox environment, this token will have the format `processor-sandbox-xxx`. - `account_holder` union, required: The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays). - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `first_name` string, required: The legal first name of the account holder. - `last_name` string, required: The legal last name of the account holder. - `tax_id` string: The legal account holder's tax number or reference. - `date_of_birth` string, date: The account holder's date of birth in a `YYYY-MM-DD` format. Strongly recommended where available. - `country_of_birth` string: The two-letter ISO country code of the account holder's country of birth. - `residential_status` 'resident' | 'non_resident': The account holder's residential status. - `billing_address` Address, required - … - `phone` PhoneNumber: A phone number - … - `identification` object: The account holder's government document identification. For example, the social security number (SSN). - … - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `company_name` string, required: The full legal name of a registered company that holds the account. - `tax_id` string: The legal account holder's tax number or reference. - `billing_address` Address - … - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `company_name` string, required: The full legal name of a registered company that holds the account. - `tax_id` string: The legal account holder's tax number or reference. - `billing_address` Address - … - `type` 'plaid', required: The payment source type. - object: PayNow Request Source - `type` 'paynow', required: The payment source type. - object: Octopus Pay Source - `type` 'octopus', required: The payment source type. - object: Multibanco Source - `payment_country` 'PT', required: The 2-letter ISO country code of the country in which the payment instrument is issued/operated. - `account_holder_name` string, required: The account holder. - `billing_descriptor` string: Payment billing descriptor. - `type` 'multibanco', required: The payment source type. - object: MobilePay Request Source - `type` 'mobilepay', required: The payment source type. - object: MBWay payment request source - `type` 'mbway', required: The payment source type. - object: KNet Source - `type` 'knet', required: The payment source type. - `language` 'ar' | 'en': Required for KNet Gateway payments. This field enables the issuer's site to select the consumer's preferred language. For example, the language selected on the merchant's site – if the issuer's site supports it. Code list in accordance with ISO 639-1. (Arabic = 'ar', English = 'en'). Note that 'ar' corresponds to 'ARA' and 'en' to 'USA'. Both values accepted by KNet Gateway. - `user_defined_field1` string: User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed - `user_defined_field2` string: User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed - `user_defined_field3` string: User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. Note that this field must be omitted when the `card_token` field is not empty. This restriction exists because a card token is passed to KNet Gateway as `user_defined_field3` - `user_defined_field4` string: User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. - `user_defined_field5` string: User-defined field that can be used to pass and store any additional transaction data required to be archived with the transaction and available as a searching criterion. Only alphanumeric characters and spaces are allowed. Note that this field must be omitted when the `ptlf` field is not empty. This restriction exists because a PTLF value is passed to KNet Gateway as `user_defined_field5` - `card_token` string: This token allows re-use of card details for multiple payments. This 8-digit token should be generated by a merchant. When a subsequent payment is initialized with the same card token, a customer is presented with two options. The customer can choose to pay with KFast (doesn't need to enter card details again), or with KNet as usual. The payment flow stays the same i.e. a merchant should redirect a customer to the redirect URL which is provided in the payment creation response. Note that `user_defined_field3` must be omitted when the `card_token` field is not empty. This restriction exists because a card token is passed to KNet Gateway as `user_defined_field3` - `ptlf` string: This is an ID for merchant PTLF functionality tracking. Only alphanumeric characters are allowed. Note that `user_defined_field5` must be omitted when the `ptlf` field is not empty. This restriction exists because a PTLF value is passed to KNet Gateway as `user_defined_field5`. - `token_type` 'applepay': The token type. This field is always `applepay` for KNet Apple Pay payments. - `token_data` TokenData: The Apple Pay payment token - `version` string: Version information about the payment token. The token uses `EC_v1` for ECC-encrypted data, and `RSA_v1` for RSA-encrypted data - `data` string: Encrypted payment data. Base64 encoded as a string - `signature` string: Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm - `header` object: Additional version-dependent information used to decrypt and verify the payment - `payment_method_details` object: The payment data received in the Apple Pay payload. Required for Apple Pay payments. - `display_name` string: The payment type display name. - `type` string: The payment method type. - `network` string: The card network. - object: iDEAL Source - `description` string, required: Description of the product(s) or services being paid for. This field must not contain characters that can lead to problems (for example those occurring in HTML editing codes). To prevent any possible errors most iDEAL systems will reject any description that contains HTML-tags and such other code. - `language` string: This field enables the issuer's site to select the consumer's preferred language. For example, the language selected on the merchant's site – if the issuer's site supports it. Code list in accordance with ISO 639-1. (Dutch = 'nl', English = 'en'). If a non-supported or non-existing language is entered, the standard language of the issuer is used. Because not all issuers support other languages, it is recommended to send 'nl' by default. - `type` 'ideal', required: The payment source type. - object: Fawry Source - `description` string, required: The payment description. - `customer_profile_id` string: The customer's id within merchant's system. - `customer_email` string, required: The customer's email address. - `customer_mobile` string, required: The customer's mobile phone number. - `expires_on` string, date-time: The date on which the payment expires. - `products` object[], required: List of Products - `product_id` string, required: The id of the product. - `quantity` integer, required: The quantity of the product. - `price` integer, required: The price of the item. Expressed using Checkout.com's standard rules for calculating payment values. - `description` string, required: The description of the product. - `type` 'fawry', required: The payment source type. - object: EPS Source - `type` 'eps', required: The payment source type. - `purpose` string, required: Purpose of the payment as appearing on customer's bank statement. - `account_holder` AccountHolderEps: The account holder details - `first_name` string, required: The first name of the account holder - `last_name` string, required: The last name of the account holder - object: Bizum Source - `type` 'bizum', required: The payment source type. - object: Blik source. Use this to process Blik payments in Poland. When `source.type` is `blik`: - `currency` must be `PLN`. - `amount` must not exceed `5000000` (in the [minor currency unit](https://www.checkout.com/docs/resources/calculating-the-amount)). - `reference` is limited to 35 characters. For customer-initiated payments (`merchant_initiated: false`), provide the customer's 6-digit Blik code in `processing.partner_code`. This applies to one-off (`payment_type: Regular`) payments and to the initial payment of a recurring agreement (`payment_type: Recurring`). For merchant-initiated recurring payments (`merchant_initiated: true`), use either: - `source.type: id` with a `source.id` value returned from a previous Blik recurring payment, or - `source.type: blik` with `partner_agreement_id` set to an external Blik PAYID created with another PSP. - `type` 'blik', required: The payment source type. - `partner_agreement_id` string: The Blik PAYID identifying an external partner agreement created with another PSP. Only used when processing merchant-initiated recurring payments (`merchant_initiated: true`) without a stored Checkout.com source. - object: Bancontact Source - `payment_country` 'BE', required: The 2-letter ISO country code of the country in which the payment instrument is issued/operated. - `account_holder_name` string, required: The account holder. - `billing_descriptor` string: Payment billing descriptor. - `language` 'fr' | 'nl' | 'de' | 'en': The 2-letter ISO language code that should be preferred when presenting payment pages to the consumer. - `type` 'bancontact', required: The payment source type. - object: Alma payment source - `type` 'alma', required: The payment source type. - `billing_address` object: The billing address of the cardholder - `address_line1` string, required: 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, required: 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, required: The two-letter ISO country code of the address. - object: Alipay CN Source - `type` 'alipay_cn', required: The payment source type. - object: Alipay HK Source - `type` 'alipay_hk', required: The payment source type. - object: Alipay Plus Source - `type` 'alipay_plus', required: The payment source type. - object: Dana Source - `type` 'dana', required: The payment source type. - object: GCash Source - `type` 'gcash', required: The payment source type. - object: Kakaopay Source - `type` 'kakaopay', required: The payment source type. - object: TNG Source - `type` 'tng', required: The payment source type. - object: TrueMoney Source - `type` 'truemoney', required: The payment source type. - object: An ach payment source - `account_type` 'savings' | 'checking' | 'cash', required: The type of Direct Debit account - `country` string, required: The source country - `account_number` string, required: The account number of the Direct Debit account - `bank_code` string, required: The bank code of the Direct Debit account - `account_holder` object, required: The account holder details - `type` 'individual' | 'corporate' | 'government', required: The type of account holder - `first_name` string, required: The first name of the account holder - `last_name` string, required: The last name of the account holder - `company_name` string: The legal name of a registered company that holds the account - `billing_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. - `date_of_birth` string: The account holder's date of birth. - `identification` object: The account holder's government document identification. For example, the social security number (SSN). - `type` string: The document type - `issuing_country` string: The country where the document was issued - `number` string: The document number - `account_name_inquiry` boolean: Whether to perform an Account Name Inquiry (ANI) check, which verifies the account holder's name against the name registered to the bank account - `allow_partial_match` boolean: Whether the payment proceeds when the Account Name Inquiry check returns a partial match. When `true`, the payment proceeds on a partial match; when `false`, the payment is declined on a partial match. - `type` 'ach', required: The payment source type. - object: A token payment source - `type` 'token', required: The payment source type. - `token` string: The Checkout.com token (e.g., a card token) - `billing_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`. - `store_for_future_use` boolean: This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response. - `account_holder` object: Information about the account holder of the card - object: A network token payment source - `token` string, required: The network token PAN - `expiry_month` integer, required: The expiry month of the token - `expiry_year` integer, required: The expiry year of the token - `token_type` 'vts' | 'mdes' | 'applepay' | 'googlepay', required: The type of token - `cryptogram` string, required: The Base64 encoded cryptographic identifier (TAVV) used by card schemes to validate the token verification result. Optional if `previous_payment_id` is specified and `3ds.enabled` is false - `eci` string, required: The Electronic Commerce Indicator (ECI) security level associated with the token. Optional if `previous_payment_id` is specified and `3ds.enabled` is false - `stored` 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. - `store_for_future_use` boolean: This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response. - `name` string: The customer's name - `cvv` string: The card verification value/code. 3 digits, except for American Express (4 digits) - `billing_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`. - `account_holder` object: Information about the account holder of the card - `type` 'network_token', required: The payment source type. - object: An existing payment source. Payment Method required for ACH payment - `id` string, required: The payment source identifier (e.g., a card source identifier) - `cvv` string: The card verification value (CVV) or code, if the source is a card. The expected format varies: - for American Express cards, this should be a 4-digit code - for other cards, this should be a 3-digit code - for Checkout.com CVV tokens, this should be an ID value with the prefix `tok_` - `payment_method` string: The payment method. Payment Method required for ACH payment - `billing_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`. - `account_holder` object: Information about the account holder of the payment instrument - `allow_update` boolean: Specifies whether to use the Real-Time Account Updater to update the card information. - `type` 'id', required: The payment source type. - object: A customer source - `id` string, required: The customer's identifier. - `billing_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`. - `account_holder` object: Information about the account holder of the customer's default payment instrument - `allow_update` boolean: Specifies whether to use the Real-Time Account Updater to update the card information. - `type` 'customer', required: The payment source type. - `fallback_source` PaymentRequestFallbackSource: A card payment source - `number` string, required: The card number (without separators) - `expiry_month` integer, required: The expiry month of the card - `expiry_year` integer, required: 4-digit expiry year of the card - `name` string: The name of the cardholder - `cvv` string: The card verification value/code. 3 digits, except for American Express (4 digits) - `stored` 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. - `store_for_future_use` boolean: This must be set to true if you intend to reuse the payment credentials in subsequent payments. Setting the field as false will mean that a payment instrument will not be included in the payment response. - `billing_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`. - `account_holder` object: Information about the account holder of the card - `allow_update` boolean: Specifies whether to use the Real-Time Account Updater to update the card information. - `type` 'card', required: The payment source type. - `amount` integer: The payment amount. To perform a card verification, do not provide the amount or provide a value of `0`. The amount must be provided in the minor currency unit. - `currency` string, required: The three-letter ISO currency code - `payment_type` 'Regular' | 'Recurring' | 'MOTO' | 'Installment' | 'PayLater' | 'Unscheduled': The type of payment. This field is required for card payments in which the cardholder is not present. For example, mail orders, telephone orders, or merchant-initiated transactions (MITs) in a [recurring payment](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details/recurring-payments-with-stored-card-details) series. For MITs, this field must not be set to `Regular`. - `payment_plan` union: The details of a recurring subscription or installment - object: 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`). - object: The information to process a installment payment request. To be used when the `payment_type` is `installment`. - `financing` boolean: If the installment plan has financing. - `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`). - `merchant_initiated` boolean: Whether the payment is a merchant-initiated transaction (MIT). Must be set to `true` for all MITs. If you set this field to `true`, the value for `payment_type` must not be set to `Regular`. - `reference` string: A reference you can use to identify the payment. For example, an order number. - For Amex payments, the reference has a 30-character limit. - For Benefit payments, the reference must be a unique alphanumeric value. - For Blik payments, the reference has a 35-character limit. - For Discover payments, the reference has a 60-character limit. - For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit. - For OmanNet payments, the reference must be a unique alphanumeric value between 12 and 30 characters long, generated for every payment action. - For seQura payments, the reference is required and must be a unique value. - For TWINT payments, the reference has a 50 character limit. - `description` string: A description of the payment. - `authorization_type` 'Final' | 'Estimated': The authorization type - `partial_authorization` PartialAuthorization: Required information to allow partial authorization - `enabled` boolean, required: Specifies whether to allow partial authorizations. - `capture` boolean: Whether to capture the payment (if applicable) - `capture_on` string, date-time: ISO 8601 timestamp - `expire_on` string, date-time: ISO 8601 timestamp - `customer` CustomerRequest: The customer's details. Required if `source.type` is `tamara` - `id` string: The identifier of an existing customer - `email` string, email: The customer's email address. If `source.type` is set to `sequra`, this field is required. If `source.type` is set to `tamara`, this field is required and has a maximum length of 50 characters. - `name` string: The customer's name. Required if `source.type` is: - `alipay_cn` - `alipay_hk` - `alipay_plus` - `dana` - `gcash` - `kakaopay` - `sequra` - `tamara` - `tng` - `truemoney` - `tax_number` string: Contains the customer's value-added tax (VAT) registration number. - `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`. - `summary` CustomerSummary: 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. - `billing_descriptor` BillingDescriptor: An optional description that is displayed on the customer's statement identifying a purchase. - `name` string, required: A dynamic description of the payment. Applies to card payments only. - `city` string, required: The city from which the payment originated. Applies to card payments only. - `reference` string: The reference that should be shown on the statement. Required for payouts to bank accounts. - `local_descriptors` LocalBillingDescriptor[], nullable - `name` string, required: A dynamic description of the card payment. Other payment methods will not display this description. The character set specified will determine the maximum length of the field. For `katakana`, the maximum length is 23 characters, equivalent to 23 katakana characters. For `kanji`, the maximum length is 40 characters, equivalent to 20 kanji characters. - `character_set` 'kanji' | 'katakana', required: The character set of the descriptor - `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. - `3ds` union: Information required for 3D Secure authentication payments. - union: Required information to process a 3DS authentication with the payment request - object: 3DS authentication not enabled - `enabled` 'true' | 'false', required: Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated. - `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: Indicates whether to process this payment as 3D Secure if the authorization was soft declined due to 3DS authentication required. For processing channels created before October 12, 2022, the value will default to `false`. - `exemption` 'low_value' | 'trusted_listing' | 'trusted_listing_prompt' | 'transaction_risk_assessment' | '3ds_outage' | 'sca_delegation' | 'out_of_sca_scope' | 'low_risk_program' | 'recurring_operation' | 'data_share' | 'other': Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide - object: 3DS authentication enabled - `enabled` 'true' | 'false', required: Whether to process this payment as a 3D Secure payment. Payments where `merchant_initiated` is `true` will be processed as 3DS Requestor Initiated. - `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. - `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. - `exemption` 'low_value' | 'trusted_listing' | 'trusted_listing_prompt' | 'transaction_risk_assessment' | 'data_share': Specifies an exemption reason so that the payment is not processed using 3D Secure authentication. Learn more about exemptions in our SCA compliance guide - `merchant_authentication_info` MerchantAuthenticationInfo: The information about how the 3DS Requestor authenticated the cardholder before or during the transaction - `three_ds_req_auth_method` 'no_threeds_requestor_authentication_occurred' | 'three3ds_requestor_own_credentials' | 'federated_id' | 'issuer_credentials' | 'third_party_authentication' | 'fido_authenticator' | 'fido_authenticator_fido_assurance_data_signed' | 'src_assurance_data': The mechanism used by the cardholder to authenticate with the 3DS Requestor - `three_ds_req_auth_timestamp` string, date-time: The UTC date and time the cardholder authenticated with the 3DS Requestor, in ISO 8601 format. - `three_ds_req_auth_data` string: The data that documents and supports a specific authentication process - `account_info` AccountInfo: Additional information about the cardholder's account - `purchase_count` number: The number of purchases with this cardholder's account during the last six months - `account_age` 'no_account' | 'created_during_transaction' | 'less_than_thirty_days' | 'thirty_to_sixty_days' | 'more_than_sixty_days': The length of time that the payment account was enrolled in the cardholder's account - `add_card_attempts` number: The number of _Add Card_ attempts in the last 24 hours - `shipping_address_age` 'this_transaction' | 'less_than_thirty_days' | 'thirty_to_sixty_days' | 'more_than_sixty_days': Indicates when the shipping address for this transaction was first used - `account_name_matches_shipping_name` boolean: Indicates if the cardholder name on the account is identical to the shipping name used for this transaction - `suspicious_account_activity` boolean: Indicates whether suspicious activity on the cardholder account has been observed - `transactions_today` number: The number of transactions (successful and abandoned) for the cardholder account across all payment accounts in the previous 24 hours - `authentication_method` 'no_authentication' | 'own_credentials' | 'federated_id' | 'issuer_credentials' | 'third_party_authentication' | 'fido': Information about how the cardholder was authenticated before or during the transaction - `cardholder_account_age_indicator` 'no_account,' | 'this_transaction' | 'less_than_thirty_days' | 'thirty_to_sixty_days' | 'more_than_sixty_days': The length of time the cardholder has held the account with the 3DS Requestor - `account_change` string, date-time: The UTC date and time the cardholder’s account with the 3DS Requestor was last changed, in ISO 8601 format. Changes that affect this value include: - updating the billing or shipping address - adding a new payment account - adding a new user - `account_change_indicator` 'this_transaction' | 'less_than_thirty_days' | 'thirty_to_sixty_days' | 'more_than_sixty_days': The amount of time since the cardholder’s account information with the 3DS Requestor was last changed. Changes that affect this value include: - updating the billing or shipping address - adding a new payment account - adding a new user - `account_date` string, date-time: The UTC date and time the cardholder opened the account with the 3DS Requestor, in ISO 8601 format. - `account_password_change` string, date-time: The UTC date and time the cardholder’s account with the 3DS Requestor was last reset or had a password change, in ISO 8601 format. - `account_password_change_indicator` 'no_change' | 'this_transaction' | 'less_than_thirty_days' | 'thirty_to_sixty_days' | 'more_than_sixty_days': The amount of time since the cardholder’s account with the 3DS Requestor was last reset or had a password change. - `transactions_per_year` integer: The number of transactions associated with the cardholder's account with the 3DS Requestor in the previous year. This value includes both successful and abandoned transactions, across all payment accounts. Set this value to `999` if the number of transactions is `1000` or greater. - `payment_account_age` string, date-time: The UTC date and time the payment account was enrolled in the cardholder’s account with the 3DS Requestor, in ISO 8601 format. - `shipping_address_usage` string, date-time: The UTC date and time the shipping address used for the transaction was first used with the 3DS Requestor, in ISO 8601 format. - `account_type` 'not_applicable' | 'credit' | 'debit': The type of account, in the case of a card product with multiple accounts. - `account_id` string: Additional information about the account optionally provided by the 3DS Requestor - object: Required information to process a payment that has been 3DS authenticated using our Standalone authentication - `enabled` true, required: Whether to process this payment as a 3D Secure payment - `authentication_id` string, required: The unique identifier for your 3D Secure session. - object: Required information to process a payment that has been 3DS authenticated using a Third Party provider - `enabled` true, required: Whether to process this payment as a 3D Secure payment - `eci` string, required: The Electronic Commerce Indicator security level associated with the 3D Secure enrollment result. Required if using a third-party merchant plug-in (MPI) - `cryptogram` string, required: A Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the cardholder authentication result (3D Secure). Required if using an external MPI - `xid` string, required: The 3D Secure transaction identifier. Required if using an external MPI with 3D Secure 2.X.X and a Mastercard card, or with 3D Secure 1.X.X for any supported card scheme - `version` string, required: Indicates the version of 3D Secure that was used for authentication. Defaults to 1.0.0 if not provided - `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 - `status` string: The transaction status returned from the card Issuer’s Access Control Server (ACS) or Scheme Directory Server (DS). For 3DS Secure 1, this is the PaRes Status. for 3D Secure 2, this is the transaction status of ARes(frictionless flow) or RReq (Challenge flow) - `authentication_date` string, nullable: Authentication date and time. Format ISO-8601 - `authentication_amount` number, nullable: Authentication amount - `flow_type` 'challenged' | 'frictionless' | 'frictionless_delegated': Indicates whether the 3D Secure 2 authentication was challenged or frictionless. - `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. - `status_reason_code` string: A code indicating the reason for the transaction status - `challenge_cancel_reason` string: Indicates a cancel reason for a challenge in the case of authentication. Can be any number from 00 to 99, with 00 being specific ONLY to Cartes Bancaires. - `score` string: Risk score calculated by Directory Server (DS). Cartes Bancaires 3D Secure 2 only. - `cryptogram_algorithm` string: The algorithm used by the Issuer Access Control Server (ACS) to calculate the Authentication cryptogram. This is the AVALGO data returned in Cartes Bancaires Authentication. - `initial_authentication` InitialAuthentication: The details of a previous transaction - `acs_transaction_id` string: The Access Control Server (ACS) transaction ID for a previously authenticated transaction - `authentication_method` 'frictionless_authentication' | 'challenge_occurred' | 'avs_verified' | 'other_issuer_methods' - `authentication_timestamp` string: The timestamp of the previous authentication, in ISO 8601 format. - `authentication_data` string: The data that documents and supports a specific authentication process - `initial_session_id` string: The ID for a previous session, which is used for retrieve the initial transaction's properties - `authentication` PaymentAuthenticationRequest - `preferred_experiences` string[]: An ordered list of preferred authentication experiences to attempt for the payment request. - `processing_channel_id` string: The processing channel to be used for the payment - `previous_payment_id` string: An identifier that links the payment to an existing series of payments. You must only pass this field if the transaction is a merchant-initiated transaction (MIT) in a recurring payment series. To link the payment, pass one of the following as its value: - a payment identifier (for example, `pay_cr4hxwizzp6k7biycuk2ibltnm`) from the recurring series, or - the scheme transaction ID - `risk` RiskRequest: Configures the risk assessment performed during the processing of the payment - `enabled` boolean: Whether a risk assessment should be performed - `device_session_id` string: Device session ID collected from our standalone Risk.js package. If you integrate using our [Frames](https://www.checkout.com/docs/integrate/frames) solution, this ID is not required. - `device` DeviceDetails: Details of the device from which the payment originated. - `user_agent` string: The contents of the HTTP User-Agent request header. This field is required to process the device with the risk engine. - `network` Network: Details of the device network. Either ipv4 or ipv6 is required field. - `ipv4` string: The device's IPV4 address. Not required if you provide the `ipv6` field. - `ipv6` string: The device's IPV6 address. Not required if you provide the `ipv4` field. - `tor` boolean: Specifies if the Tor network was used in the browser session. - `vpn` boolean: Specifies if a virtual private network (VPN) was used in the browser session. - `proxy` boolean: Specifies if a proxy was used in the browser session. - `provider` DeviceProvider: Details of the device ID provider. - `id` string: The unique identifier for the device. - `name` string: The name of the provider that generated the device identifier. - `timestamp` string: The UTC date and time the payment was performed as reported by the device.
Format – ISO 8601 code This field is required to process the device with the risk engine. - `timezone` string: The time difference between UTC time and the local time reported by the browser, in minutes. This field is required to process the device with the risk engine. - `virtual_machine` boolean: Specifies if the device is running in a virtual machine. - `incognito` boolean: Specifies if the browser is in incognito mode. - `jailbroken` boolean: Specifies if the device is jailbroken. - `rooted` boolean: Specifies if the device is rooted. - `java_enabled` boolean: Specifies if the browser has the ability to execute Java, as reported by the browser's `navigator.javaEnabled` property. - `javascript_enabled` boolean: Specifies if the browser has the ability to execute Javascript, as reported by the browser's `navigator.javascriptEnabled` property. Only required for 3D Secure authentications processed with 3DS 2.2. If the payment is processed with an older 3DS version, this field is ignored. - `language` string: The browser language, as reported by the browser's `navigator.language` property.
Format – IETF BCP47 language tag - `color_depth` string: The bit depth of the color palette for displaying images in bits per pixel, as reported by the browser's `screen.colorDepth` property. - `screen_height` string: The total height of the device screen in pixels, as reported by the browser's `screen.height` property. - `screen_width` string: The total width of the device screen in pixels, as reported by the browser's `screen.width` property. - `user_agent_client_hint` string: The raw `Sec-CH-UA` header value. This field improves Google Single-Page Application (SPA) support, as it provides more accurate information about the customer's browser. - `iframe_payment_allowed` boolean: Indicates whether the Payments API is enabled for all parent frames. - `accept_header` string: The exact content of the HTTP `Accept` headers as sent to the 3DS Requestor from the cardholder’s browser. - `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 - `payment_ip` string, ipv4 - `sender` union: Information about the sender of the payment's funds - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'instrument', required: The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument. - `reference` string: The unique reference for the sender of the payment. - `first_name` string, required: The sender's first name - `last_name` string, required: The sender's last name - `date_of_birth` string, date: The sender's date of birth (yyyy-mm-dd) - `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. - `identification` object - `type` 'passport' | 'driving_licence' | 'national_id': The type of identification used to identify the sender - `number` string: The identification number - `issuing_country` string: The two-letter ISO country code of the country that issued the identification - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'instrument', required: The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument. - `reference` string: The unique reference for the sender of the payment. - `company_name` string, required: The sender's company name - `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. - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'instrument', required: The sender type. If set to `instrument`, the sender information (name and address) will be retrieved from the payment instrument. - `reference` string: The unique reference for the sender of the payment. - `recipient` PaymentRecipient: Information about the recipient of the payment's funds. Relevant for [Account Funding Transactions](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions) and VISA or Mastercard [domestic UK transactions processed by financial institutions](https://www.checkout.com/docs/payments/regulation-support/requirements-for-financial-institutions). - `dob` string, date: The recipient's date of birth (yyyy-mm-dd) - `account_number` string: Any identifier like part of the PAN (first six digits and last four digits), an IBAN, an internal account number, or a phone number related to the primary recipient's account - `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. - `zip` string: Replaced by `address.zip` The first part of the UK postcode (e.g., SW1A 1AA would be SW1A). - `first_name` string: The recipient's first name - `last_name` string: The recipient's last name - `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. - `processing` PaymentRequestProcessing: Use the processing object to influence or override the data sent during card processing - `order_id` string: The number provided by the cardholder. Purchase order or invoice number may be used. - `tax_amount` number: The total amount of sales tax on the total purchase amount. - `surcharge_amount` integer: Surcharge amount applied to the transaction in minor units by the merchant. - `discount_amount` number: The discount amount applied to the transaction by the merchant. - `duty_amount` number: The total charges for any import/export duty included in the transaction. - `shipping_amount` number: The total freight or shipping and handling charges for the transaction. - `shipping_tax_amount` number: The tax amount of the freight or shipping and handling charges for the transaction. - `aft` boolean: Indicates if the payment is an [Account Funding Transaction](https://www.checkout.com/docs/payments/manage-payments/account-funding-transactions) - `preferred_scheme` 'mastercard' | 'visa' | 'cartes_bancaires' | 'accel' | 'discover' | 'eftpos' | 'maestro' | 'nyce' | 'pulse' | 'star': The preferred scheme for co-badged and PINless debit card payment processing. If performing 3DS via a third party, set this value to the scheme that processed 3DS. - `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. - `product_type` string: Product type of the payment. Used when `source.type` is

- `open_id` string: Value obtained from WeChat Web Authorization API before initiating Official Account or Mini Program payments. Required if `source.type` is `wechatpay` and `processing.product_type` is `Official Account` or `Mini Program`. - `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. - `terminal_type` 'APP' | 'WAP' | 'WEB': The client-side terminal type, if it is a website that is opened via a PC browser or a mobile browser or mobile application. - `os_type` 'ANDROID' | 'IOS': This field is required when `terminalType` is not `WEB`. - `invoice_id` string: Invoice ID number. - `locale` string: The language and region of the customer in ISO 639-2 language code; value consists of language-country. - `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. - `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.
Note: This only works for source.type cards, instruments and tokens. * **DPAN**: Indicates a preference for using the Checkout.com Network Token. * **FPAN**: Indicates a preference for using the full card number. - `service_type` 'same_day' | 'standard': Specifies which ACH service to use for the payment, if you set `source.type` to `ach`. - `partner_code` string: The customer's 6-digit Blik code. Required when `source.type` is `blik` and `merchant_initiated` is `false` (For example, for `Regular` payments and the initial payment of a `Recurring` agreement). - `provision_network_token` boolean: Indicates whether to provision a network token for the payment. - `card_type` 'credit' | 'debit': Specifies whether to process the payment as a credit or debit transaction, if a combo card is used. This field is required for domestic payments in Brazil performed using a Brazilian card. - `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 two-letter ISO country code of the purchase country. If you're a Visa-registered ramp provider operating with affiliates, this field is required. - `foreign_retailer_amount` integer: The foreign retailer amount the merchant applied to the transaction, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). - `reconciliation_id` string: The transaction identifier to track a payment request. - `aggregator` Aggregator: Information about the payment aggregator. - `sub_merchant_id` string: The sub-merchant ID. - `aggregator_id_visa` string: The Visa identifier for the payment aggregator. - `aggregator_id_mc` string: The Mastercard identifier for the payment aggregator. - `scheme_transaction_link_id` string: The scheme transaction link identifier. - `items` object[]: The order's line items. - `type` 'digital' | 'discount' | 'physical': The item type. For example, `physical` or `digital`. This field is used to provide item level metadata where applicable. If `source.type` is `sequra`, this field is required. - `sub_type` 'blockchain' | 'cbdc' | 'cryptocurrency' | 'nft' | 'stablecoin': The digital item type. If `type` is set to `digital`, this field is required. - `name` string: The descriptive name of the line item. If `source.type` is `sequra`, this field is required. - `quantity` integer: The number of line items. If `source.type` is `sequra`, this field is required. - `unit_price` integer: The unit price of the item the minor currency unit. Required if `source.type` is `sequra` - `reference` string: The item reference or product SKU (stock-keeping unit). For Visa and Mastercard's interchange reduction programs, this value has a maximum length of 12 characters. If `source.type` is `sequra`, this field is required. - `commodity_code` string: A code identifying a Commodity for value-added tax (VAT) purposes. - `unit_of_measure` string: Unit of Measure code used for an item in transaction. - `total_amount` number: The total cost of the line item, in minor currency units. Calculate this using the following formula: `total_amount` = (`quantity` * `unit_price`) - `discount_amount`. If `source.type` is `sequra`, this field is required. - `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: Contains the total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase. - `tax_exempt` boolean: Indicates whether the products or services are tax-exempt.

Set to `true` if: - You are processing a card payment. - The `tax_amount` field is `0` due to a tax-exempt product or service. - `discount_amount` number: The discount applied to each invoice line item. - `wxpay_goods_id` string: Unified product No. defined by WeChat Pay - `url` string: Link to the line item's product page - `image_url` string: Link to the line item's product page - `service_ends_on` string, date: Maximum date for the service to be rendered or ended. If `source.type` is `sequra` and `item.type` is `digital`, this field is required. - `purchase_country` string: The country where the purchase was made.
Format – ISO alpha-2 country code - `foreign_retailer_amount` integer: The foreign retailer amount the merchant applied to the transaction, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). - `retry` RetryRequest: Configuration of asynchronous retries. For more information about asynchronous retries and supported response codes, see [Configure scheduled retries](https://www.checkout.com/docs/payments/manage-payments/configure-scheduled-retries). - `enabled` boolean, required: Indicates whether asynchronous retries are enabled for the payment. - `dunning` DunningRetryRequest: Configuration of Dunning retries. - `enabled` boolean, required: Indicates if Checkout.com retries the payment when it's declined with a supported decline code. - `max_attempts` integer: The maximum number of authorization retry attempts, excluding the initial authorization. - `end_after_days` integer: The maximum number of days between the initial request and the final retry attempt. - `downtime` DowntimeRetryRequest: Configuration of Downtime retries. - `enabled` boolean, required: Indicates if Checkout.com retries the payment when it's declined due to issuer or acquirer downtime. - `subscription` Subscription: The details of the subscription. - `id` string: The ID or reference linking a series of recurring payments together. - `metadata` object: Stores additional information about a transaction with custom fields and up to five user-defined fields, which you can use for reporting purposes. The object supports `string`, `number`, and `boolean` fields, but not arrays or objects. 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. For example, `$coupon_code = '1234’`. - `segment` Segment: The dimension details about business segment for payment request. At least one dimension required. - `brand` string: The brand of business segment. - `business_category` string: The category of business segment. - `market` string: The market of business segment. - `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. - `routing` object: Controls processor attempts at the payment level. - `attempts` Attempt[]: Specifies the processing rules for the payment. Each object in the array should be a unique expression of rules that determine the routing attempts to process the payment with. For example: ``` "attempts": [ { "scheme": "mastercard" }, { "scheme": "visa" } ] ``` - `scheme` 'accel' | 'amex' | 'cartes_bancaires' | 'diners' | 'discover' | 'jcb' | 'mada' | 'maestro' | 'mastercard' | 'nyce' | 'omannet' | 'pulse' | 'shazam' | 'star' | 'upi' | 'visa': The card scheme to use for the payment attempt. - PaymentContextPaymentRequest - `payment_context_id` string, required: Payment Context's unique identifier. - `amount` integer: The payment amount. The amount must be provided in the minor currency unit. - `reference` string: A reference you can later use to identify this payment, 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. - `processing_channel_id` string: The processing channel to be used for the payment context. Required if this was not set in the request for the OAuth token. - `processing` object: Use the processing object to influence or override the data during the payment processing. - `invoice_id` string: The identification number of the invoice. - `shipping_amount` number: The total freight or shipping and handling charges for the transaction. - `discount_amount` number: The discount amount. - `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). - `otp_value` string: One time password sent to customer by SMS.
Required if `source.type` is `StcPay`. - `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. - `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. - `segment` Segment: The dimension details about business segment for payment request. At least one dimension required. - `brand` string: The brand of business segment. - `business_category` string: The category of business segment. - `market` string: The market of business segment. - CardPayoutRequest - `source` object, required: The source of the payout. - `type` 'currency_account', required: The payout source type. - `id` string, required: The ID of the currency account that will fund the payout. - `destination` CardPayoutRequestDestination, required: The destination of the payout. You can encrypt this field by using the `Cko-Encryption-Key-Id` and `Cko-Encrypted-Properties` [headers](https://api-reference.checkout.com/tag/payments/POST/payments.headers.Cko-Encryption-Key-Id). - `type` string, required - `amount` integer: The amount to pay out, in minor units. Use the [specific format](https://www.checkout.com/docs/payments/accept-payments/calculating-the-amount) for the `currency` you specify for the payout. - `currency` string, required: The [three-letter ISO 4217 code](https://www.checkout.com/docs/developer-resources/codes/currency-codes) for the currency you want to pay out to the recipient. - `instruction` object, required: Additional details about the payout instruction. - `funds_transfer_type` string, required: The [funds transfer type](https://www.checkout.com/docs/payments/request-payouts/card-payouts#Fund_Transfer_Types) code for the type of payout you're performing. You can only use codes that have been assigned to you by the card schemes and Checkout.com, based on your business case and requirements. If you have only been assigned one funds transfer type code, this field is optional. - `purpose` 'family_support' | 'expatriation' | 'travel_and_tourism' | 'education' | 'medical_treatment' | 'emergency_need' | 'leisure' | 'savings' | 'gifts' | 'donations' | 'financial_services' | 'it_services' | 'investment' | 'insurance' | 'loan_payment' | 'pension' | 'royalties' | 'other' | 'income': The purpose of the payout. This field is required if the card's `issuer_country` is one of: - `AR` (Argentina) - `BD` (Bangladesh) - `CL` (Chile) - `CO` (Colombia) - `EG` (Egypt) - `IN` (India) - `MX` (Mexico) - `SA` (Saudi Arabia) 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). - `items` object[]: The order's line items. - `type` 'digital' | 'physical': The item type. For example, `physical` or `digital`. This field is used to provide item level metadata where applicable. - `sub_type` 'blockchain' | 'cbdc' | 'cryptocurrency' | 'nft' | 'stablecoin': The digital item type. If `type` is set to `digital`, this field is required. - `processing_channel_id` string, required: The unique identifier for the processing channel. - `sender` CardPayoutRequestSender: The sender of the payout. This field is required for [money transfer](https://www.checkout.com/docs/payments/request-payouts/card-payouts#Fund_Transfer_Types) card payouts. - `type` string, required - `reference` string: A custom reference to identify the payout. For example, an order number. - `previous_payment_id` string: The identifier of an existing payment from the recurring series, if the payout is a recurring payment that uses stored card details. If the card payout is linked to a previous Account Funding Transaction (AFT), you must include this field in your request with one of the following values: - If the previous AFT was processed by Checkout.com, use the previous payment's ID. - If the previous AFT was processed by another payment service provider (PSP), use the scheme's transaction ID. - `metadata` object: Stores additional information about the transaction with custom fields. You can also provide up to five user-defined fields (`udf1` to `udf5`), for your reporting purposes. `udf1` is also used for some of our risk rules. You can only supply primitive data types with one level of depth. Fields of type `object` or `array` are not supported. - `segment` Segment: The dimension details about business segment for payment request. At least one dimension required. - `brand` string: The brand of business segment. - `business_category` string: The category of business segment. - `market` string: The market of business segment. - `processing` object: Returns information related to the processing of the payment. - `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. - `processing_speed` 'fast': The speed at which the payout is processed. Only applicable for unreferenced refunds. - `purchase_country` string: The two-letter ISO country code of the purchase country. If you're a Visa-registered ramp provider operating with affiliates, this field is required. - BankPayoutRequest - `source` union, required: The source from which the payout is funded. - object: A currency account source. - `type` string, required: The payout source type. - `id` string, required: The currency account's identifier.
Its holding currency must match the payout's `currency`. - object: A currency account source. - `type` string, required: The payout source type. - `id` string, required: The entity or sub-entity's identifier, only applies to Platform Clients. - `destination` union, required: The destination of the payout. You can encrypt this field by using the `Cko-Encryption-Key-Id` and `Cko-Encrypted-Properties` [headers](https://api-reference.checkout.com/tag/payments/POST/payments.headers.Cko-Encryption-Key-Id). - object: An existing payment instrument. - `type` string, required: The payout destination type. - `id` string, required: The existing payment instrument's identifier. It is advisable that payment instruments are reused, see the documentation for more information. - object: An existing payment instrument. - `type` string, required: The payout destination type. - `country` string, required: The two-letter ISO country code of where the account is based. Note that not all countries are available, see our docs for details. - `iban` string: Internationally agreed standard for identifying bank accounts. Lengths vary per `destination_country`. See the glossary for details. - `account_number` string: Number (which can contain letters) that identifies the local account. - `bank_code` string: Code that identifies the bank. Also referred as Routing Number in the United States. - `branch_code` string: Code that identifies the bank branch. - `bban` string: The combination of bank code and/or branch code and account number. - `swift_bic` string: 8 or 11 character code which identifies the bank or bank branch. - `account_type` 'savings' | 'current' | 'cash', required: The type of the bank account. Note: that some beneficiary banks do not accept payouts to savings accounts. - `account_holder` union: The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays). - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `first_name` string, required: The legal first name of the account holder. - `last_name` string, required: The legal last name of the account holder. - `tax_id` string: The legal account holder's tax number or reference. - `date_of_birth` string, date: The account holder's date of birth in a `YYYY-MM-DD` format. Strongly recommended where available. - `country_of_birth` string: The two-letter ISO country code of the account holder's country of birth. - `residential_status` 'resident' | 'non_resident': The account holder's residential status. - `billing_address` Address, required - … - `phone` PhoneNumber: A phone number - … - `identification` object: The account holder's government document identification. For example, the social security number (SSN). - … - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `company_name` string, required: The full legal name of a registered company that holds the account. - `tax_id` string: The legal account holder's tax number or reference. - `billing_address` Address - … - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `company_name` string, required: The full legal name of a registered company that holds the account. - `tax_id` string: The legal account holder's tax number or reference. - `billing_address` Address - … - `amount` integer, required: The amount to pay out. Value must be provided in the minor currency unit. For example, cents for USD. - `currency` string, required: The three-letter ISO code of the destination currency
The currency should match that of the destination account. - `reference` string: A reference you can use to identify the payment. For example, an order number. - `billing_descriptor` PayoutBillingDescriptor, required: Beneficiary banks typically construct the billing descriptor using the billing descriptor reference and sender information. For direct sellers, the sender is typically your entity’s legal company name. If the ultimate sender is provided, then it is the values of the Sender object. - `reference` string, required: The reference shown on the beneficiary's bank statement. Format – The length varies per beneficiary bank. In general, we recommend fewer than 11 characters. Note – References are not supported in the US. - `sender` union: The ultimate sender of the payout – that is, your customer. Not supported for Platform or Direct Seller Checkout.com clients. - object: Store a previously tokenized instrument - `type` 'instrument' | 'individual' | 'corporate', required: The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination. - `reference` string, required: A unique reference to the underlying client's customer. A global KYC requirement. - object: Store a previously tokenized instrument - `type` 'instrument' | 'individual' | 'corporate', required: The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination. - `reference` string, required: A unique reference to the underlying client's customer. A global KYC requirement. - `first_name` string, required: The legal first name of the ultimate sender. - `last_name` string, required: The legal last name of the ultimate sender. - `dob` string, date: The sender's date of birth in a `YYYY-MM-DD` format. Strongly recommended where available. - `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. - `identification` object - `type` 'passport' | 'driving_licence' | 'national_id': The type of identification used to identify the sender. - `number` string: The identification number. - `issuing_country` string: The two-letter ISO country code that issued the identification. - object: Store a previously tokenized instrument - `type` 'instrument' | 'individual' | 'corporate', required: The sender type. Given it is set to `instrument`, then the sender parameters are retrieved from the destination. - `reference` string, required: A unique reference to the underlying client's customer. A global KYC requirement. - `company_name` string, required: The sender's company name - `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. - `instruction` PaymentInstruction: Details about the instruction for payouts to bank accounts. - `scheme` 'local' | 'instant': An option to restrict the payment scheme type, when not available payouts will fail. - `remittance` object - `reference` string: A merchant-provided reference for the remittance payment. This value is used for payment reconciliation and is reviewed by our banking partner. - `processing_channel_id` string, required: The processing channel identifier - `segment` Segment: The dimension details about business segment for payment request. At least one dimension required. - `brand` string: The brand of business segment. - `business_category` string: The category of business segment. - `market` string: The market of business segment. - UnreferencedRefundRequest - `source` object, required: The source of the unreferenced refund. - `type` 'currency_account', required: The unreferenced refund source type. - `id` string, required: The ID of the currency account that will fund the unreferenced refund. - `destination` union, required: The destination of the unreferenced refund. - object: The destination of the unreferenced refund. - `type` string, required: The unreferenced refund destination type. - `token` string, required: The Checkout.com card token ID. This will be an ID with the prefix `tok_`. - `account_holder` union: The unreferenced refund destination account holder. - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `first_name` string: The account holder's first name. This must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all numeric characters - all punctuation characters - `middle_name` string: The account holder's middle name. - `last_name` string: The account holder's last name. This must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all numeric characters - all punctuation characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful payout. - … - `email` string: The account holder's email address. - `date_of_birth` string: The account holder's date of birth, in the format `YYYY-MM-DD`. - `country_of_birth` string: The account holder's country of birth, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes). - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `company_name` string, required: The corporate account holder's company name. This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `company_name` string, required: The account holder's company name. This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - object: The destination of the unreferenced refund. - `type` string, required: The unreferenced refund destination type. - `id` string, required: The payment source ID. This will be an ID with the prefix `src_`. - `account_holder` union: The unreferenced refund destination account holder. - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `first_name` string: The account holder's first name. This must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all numeric characters - all punctuation characters - `middle_name` string: The account holder's middle name. - `last_name` string: The account holder's last name. This must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all numeric characters - all punctuation characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful payout. - … - `email` string: The account holder's email address. - `date_of_birth` string: The account holder's date of birth, in the format `YYYY-MM-DD`. - `country_of_birth` string: The account holder's country of birth, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes). - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `company_name` string, required: The corporate account holder's company name. This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `company_name` string, required: The account holder's company name. This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - object: The destination of the unreferenced refund. - `type` string, required: The unreferenced refund destination type. - `number` string, required: The card number. - `expiry_month` integer, required: The card's expiration month. - `expiry_year` integer, required: The card's expiration year. - `account_holder` union, required: The unreferenced refund destination account holder. - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `first_name` string, required: The account holder's first name. This must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `middle_name` string: The account holder's middle name. - `last_name` string, required: The account holder's last name. This must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - `date_of_birth` string: The account holder's date of birth, in the format `YYYY-MM-DD`. - `country_of_birth` string: The account holder's country of birth, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes). - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `company_name` string, required: The corporate account holder's company name. This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `company_name` string, required: The account holder's company name. This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - object: The destination of the unreferenced refund. - `type` string, required: The unreferenced refund destination type. - `token` string, required: The network token's Primary Account Number (PAN). - `expiry_month` integer, required: The network token's expiration month. - `expiry_year` integer, required: The network token's expiration year. - `token_type` 'vts' | 'mdes' | 'applepay' | 'googlepay', required: The network token type. - `cryptogram` string: The network token's Base64-encoded cryptographic identifier (TAVV). The cryptogram is used by card schemes to validate the token verification result. - `eci` string: The network token's Electronic Commerce Indicator (ECI) security level. - `account_holder` union, required: The unreferenced refund destination account holder. - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `first_name` string, required: The account holder's first name. This must be a valid legal name. The following formats for the `first_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `middle_name` string: The account holder's middle name. - `last_name` string, required: The account holder's last name. This must be a valid legal name. The following formats for the `last_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - `date_of_birth` string: The account holder's date of birth, in the format `YYYY-MM-DD`. - `country_of_birth` string: The account holder's country of birth, as a [two-letter ISO country code](https://www.checkout.com/docs/developer-resources/codes/country-codes). - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `company_name` string, required: The corporate account holder's company name. This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - object: The unreferenced refund destination account holder's details. - `type` string, required: The type of account receiving the unreferenced refund. - `company_name` string, required: The account holder's company name. This must be a valid legal name. The following formats for the `company_name` value will return a [field validation error](https://www.checkout.com/docs/developer-resources/codes/error-codes#Field_validation_errors): - a single character - all non-alphabetic characters - `billing_address` object: The account holder's billing address. If your company is incorporated in the United States, this field is required for all unreferenced refunds you perform. - … - `phone` object: The account holder's phone number. - … - `identification` object: The account holder's identification. Providing identification details for the unreferenced refund recipient increases the likelihood of a successful unreferenced refund. - … - `email` string: The account holder's email address. - `instruction` object: Additional details about the unreferenced refund instruction. - `funds_transfer_type` string: **Required** if `processing.processing_speed` is `fast`. Value of this field should be based on the destination card scheme: - For Visa, use `MI` - For Mastercard, use `C60` - `purpose` 'family_support' | 'expatriation' | 'travel_and_tourism' | 'education' | 'medical_treatment' | 'emergency_need' | 'leisure' | 'savings' | 'gifts' | 'donations' | 'financial_services' | 'it_services' | 'investment' | 'insurance' | 'loan_payment' | 'pension' | 'royalties' | 'other' | 'income': The purpose of the unreferenced refund. This field is required if the card's `issuer_country` is one of: - `AR` (Argentina) - `BD` (Bangladesh) - `CL` (Chile) - `CO` (Colombia) - `EG` (Egypt) - `IN` (India) - `MX` (Mexico) 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). - `amount` integer, required: The amount in minor currency - `currency` string, required: The three-letter ISO currency code of the payment.
- `payment_type` 'UnreferencedRefund', required: The type of the payment - `processing_channel_id` string, required: The processing channel identifier - `reference` string: An internal reference you can later use to identify this payment - `metadata` object: A set of key-value pairs that you can attach to the refund request. It can be useful for storing additional information in a structured format. **Note**: This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays. - `previous_payment_id` string: The previous related payment identifier. This could be the ID of the payment that you want to refund. - `segment` Segment: The dimension details about business segment for payment request. At least one dimension required. - `brand` string: The brand of business segment. - `business_category` string: The category of business segment. - `market` string: The market of business segment. - `processing` object: Returns information related to the processing of the payment. - `processing_speed` 'fast': The speed at which the unreferenced refund is processed. Only applicable for unreferenced refunds. ## Response `201` Payment processed successfully - PaymentResponse: Payment Response - `id` string, required: The payment identifier. - `action_id` string, required: The action identifier - `amount` integer, required: The payment amount. - `amount_requested` integer: The full amount from the original authorization, if a partial authorization was requested and approved. - `currency` string, required: The three-letter ISO currency code of the payment - `approved` boolean, required: Whether or not the authorization or capture was successful - `status` 'Authorized' | 'Pending' | 'Card Verified' | 'Declined' | 'Retry Scheduled', required: The status of the payment - `auth_code` string: The acquirer authorization code if the payment was authorized - `response_code` string, required: The Gateway response code - `response_summary` string: The Gateway response summary - `expires_on` string: The timestamp (ISO 8601 code) for when the authorization's validity period expires - `3ds` 3dsEnrollmentData - `downgraded` boolean: Indicates whether this was a 3D Secure payment downgraded to non-3D-Secure (when `attempt_n3d` is specified) - `enrolled` string: Indicates the 3D Secure enrollment status of the issuer * `Y` - Issuer enrolled * `N` - Customer not enrolled * `U` - Unknown - `upgrade_reason` string: Indicates the reason why the payment was upgraded to 3D Secure. - `risk` object: Returns the payment's risk assessment results - `flagged` boolean: Whether or not the payment was flagged by a risk check - `score` number: The risk score calculated by our Fraud Detection engine. Absent if not enough data provided. - `source` union: Payment source in /payments successfully created response - object: A card payment source - `type` 'card', required: The payment source type. - `id` string: The payment source identifier that can be used for subsequent payments. For new sources, this will only be returned if the payment was approved - `billing_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`. - `expiry_month` integer, required: The expiry month - `expiry_year` integer, required: The expiry year - `name` string: The cardholder's name - `scheme` string: The card scheme - `scheme_local` string: Replaced by `local_schemes` The local co-branded card scheme. - `local_schemes` string[]: The local co-branded card schemes. - `last4` string, required: The last four digits of the card number - `fingerprint` string, required: Uniquely identifies this particular card number. You can use this to compare cards across customers. - `bin` string, required: The card issuer's Bank Identification Number (BIN) - `card_type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE' | 'DEFERRED DEBIT': The card type - `card_category` 'CONSUMER' | 'COMMERCIAL': The card category - `card_wallet_type` 'applepay' | 'googlepay': The card wallet type - `issuer` string: The name of the card issuer - `issuer_country` string: The card issuer's country (two-letter ISO code) - `product_id` string: The issuer/card scheme product identifier - `product_type` string: The issuer/card scheme product type - `avs_check` string: The Address Verification System check result - `cvv_check` string: The card verification value (CVV) check result - `payment_account_reference` string: A unique reference to the underlying card for network tokens (e.g., Apple Pay, Google Pay) - `encrypted_card_number` string: The JWE encrypted full card number that has been updated by real-time account updater. - `account_update_status` 'card_updated' | 'card_expiry_updated' | 'card_closed' | 'contact_cardholder': Specifies what card information was updated by the Real-Time Account Updater. - `account_update_failure_code` string: Provides the failure code if the Real-Time Account Updater fails to update the card information. - `account_holder` object: Information about the account holder of the card - object: A source-based APM Declined payment source response - `id` string, required: The payment instrument identifier - `type` 'card' | 'ach' | 'alipay_cn' | 'bank_account' | 'sepa' | 'bacs', required: The type of payment source - `customer` CustomerResponse: Stored customer details - `id` string, required: The customer's unique identifier. This can be passed as a source when making a payment. - `email` string: The customer's email address. - `name` string: The customer's name. - `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`. - `summary` CustomerSummary: 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. - `balances` PaymentResponseBalances: The balances of the payment - `total_authorized` integer: The total amount that has been authorized - `total_voided` integer: The total amount that has been voided - `available_to_void` integer: The total amount that is still available for voiding - `total_captured` integer: The total amount that has been captured - `available_to_capture` integer: The total amount that is still available for capture - `total_refunded` integer: The total amount that has been refunded - `available_to_refund` integer: The total amount that is still available for refund - `processed_on` string, date-time, required: Read-only UTC timestamp, automatically assigned by us - `reference` string: Your reference for the payment - `subscription` Subscription: The details of the subscription. - `id` string: The ID or reference linking a series of recurring payments together. - `processing` object: Returns information related to the processing of the payment - `retrieval_reference_number` string: A unique identifier for the authorization that is submitted to the card scheme during processing - `acquirer_transaction_id` string: A unique identifier for the transaction generated by the acquirer - `recommendation_code` string: A code representing the follow-up action to take with the payment, as recommended by Checkout.com - `scheme` string: The scheme the transaction was processed with - `partner_merchant_advice_code` string: The Merchant Advice Code (MAC) provided by Mastercard, which contains additional information about the transaction. For example, the MAC can inform you if the transaction was performed using a consumer non-reloadable prepaid card or a consumer single-use virtual card. For declined transactions, the MAC will also let you know whether the payment can be retried, and how long you should wait before doing so. - `partner_response_code` string: The original authorization response code sent by the scheme. This is also referred to as the raw response code. This differs from the `recommendation_code` value, which is provided by Checkout.com and is standardized across all schemes. - `partner_order_id` string: Unique order identification of an Afterpay payment - `partner_payment_id` string: Unique identification of a payment provided by partner - `partner_status` string: Status of a payment provided by partner - `partner_transaction_id` string: Unique transaction identification provided by partner - `partner_error_codes` string[]: Error codes provided by partner - `partner_error_message` string: Error description provided by partner - `partner_authorization_code` string: Authorization code provided by partner - `partner_authorization_response_code` string: Authorization response code provided by partner - `surcharge_amount` integer: Surcharge amount applied to the transaction in minor units - `pan_type_processed` 'fpan' | 'dpan': The type of Primary Account Number (PAN) used for the payment. DPAN indicates network token was used, FPAN indicates the full card was used - `fallback_source_used` boolean: Indicates whether the `fallback_source` field was used for the payment. - `cko_network_token_available` boolean: The flag indicating if Checkout Network Token was available for the payment - `purchase_country` string: The country where the purchase was made.
Format – ISO alpha-2 country code - `foreign_retailer_amount` integer: The foreign retailer amount the merchant applied to the transaction, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). - `scheme_merchant_id` string: The merchant identifier that was configured with the scheme and used for the payment. - `reconciliation_id` string: The transaction identifier to track a payment request. - `aggregator` Aggregator: Information about the payment aggregator. - `sub_merchant_id` string: The sub-merchant ID. - `aggregator_id_visa` string: The Visa identifier for the payment aggregator. - `aggregator_id_mc` string: The Mastercard identifier for the payment aggregator. - `scheme_transaction_link_id` string: The scheme transaction link identifier. - `eci` string: The final Electronic Commerce Indicator (ECI) security level used to authorize the payment. Applicable for 3D Secure and network token payments - `scheme_id` string: The scheme transaction identifier - `retry` RetryPostResponse: Configuration relating to asynchronous retries - `enabled` boolean, required: Indicates whether asynchronous retries are enabled for the payment. - `max_attempts` integer: The maximum number of authorization retry attempts, excluding the initial authorization. - `ends_on` string, date-time: ISO 8601 timestamp - `next_attempt_on` string, date-time: ISO 8601 timestamp - `_links` object, required: The links related to the payment - `self` Link, required - `href` string, required: The link URL - `actions` Link, required - `href` string, required: The link URL - `authorize` Link - `href` string, required: The link URL - `void` Link - `href` string, required: The link URL - `capture` Link - `href` string, required: The link URL - `refund` Link - `href` string, required: The link URL - `cancel` Link - `href` string, required: The link URL ## Other responses - `202`: Payment asynchronous or further action required - `401`: Unauthorized - `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)