--- title: "Submit a Payment Session" method: POST path: "/payment-sessions/{id}/submit" tags: ["Flow"] --- # Submit a Payment Session `POST /payment-sessions/{id}/submit` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/payment-sessions/{id}/submit` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `string` scopes: `gateway:payment`, `payment-sessions` - API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Submit a payment attempt for a payment session. This request works with the Flow handleSubmit callback, where you can perform a customized payment submission. You must send the unmodified response body as the response of the `handleSubmit` callback. ## Path parameters - `id` string, required: The Payment Sessions unique identifier ## Request body - SubmitPaymentSessionsRequest - `session_data` string, required: A unique token representing the additional customer data captured by Flow, as received from the handleSubmit callback. Do not log or store this value. - `amount` integer: The payment amount. Provide a value of `0` to perform a card verification. The amount must be provided in the minor currency unit. - `currency` string: The three-letter ISO currency code. - `billing` PaymentSessionBilling: The billing details. - `address` Address, required - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PaymentInterfacesPhoneNumber: A phone number - `country_code` string: The international country calling code. - `number` string: The phone number. - `items` object[]: The line items in the order. - `reference` string: The item reference or product stock keeping unit (SKU). - `commodity_code` string: A code identifying a commodity for value-added tax (VAT) purposes. - `unit_of_measure` string: The unit in which the item is measured, as a Unit of Measure (UoM) code. - `total_amount` integer: The total cost of the line item, in minor currency units. The value should include any tax and discounts applied using the formula: `value = (quantity x unit_price) - discount_amount`. - `tax_amount` integer: The total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase amount. - `discount_amount` integer: The discount applied to each invoice line item. - `url` string: Link to the line item's product page. - `image_url` string: Link to the line item's product image. - `name` string, required: The descriptive name of the line item. - `quantity` integer, required: The number of line items. - `unit_price` integer, required: The unit price of the item, in minor currency units. - `amount_allocations` object[]: The sub-entities that the payment is being processed on behalf of. - `id` string, required: The sub-entity's ID. - `amount` integer, required: The split amount, in minor currency units. The sum of all split amounts must be equal to the payment amount. The split amount will be credited to your sub-entity's currency account. - `reference` string: A reference you can use to identify the split. For example, an order number. - `commission` object: The commission you'd like to collect from the split, calculated using the formula: `commission = (amount * commission.percentage) + commission.amount`. The commission cannot exceed the split amount. Commission will be credited to your currency account. - `amount` integer: An optional commission to collect, as a fixed amount in minor currency units. - `percentage` number: An optional commission to collect, as a percentage value with up to eight decimal places. - `3ds` union - union - object: 3DS authentication not enabled - `enabled` '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', 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 - `account_info` PaymentSessions3DSAccountInfo: 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 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 - `ip_address` string, ipv4 - `payment_method_configuration` PaymentSessionsPaymentMethodConfigurationBase: Configurations for payment method-specific settings. - `applepay` object: Configuration options specific to Apple Pay payments. - `store_payment_details` 'disabled' | 'enabled': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled`, you must: - have obtained consent from the cardholder to store their payment details - provide a customer ID or email address in the request If the request's `payment_type` is set to one of the following values, you do not need to provide this field: - `Installment` - `Recurring` - `Unscheduled` - `card` object: Configuration options specific to card payments. - `store_payment_details` 'disabled' | 'enabled' | 'collect_consent': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled` or `collect_consent`, you must: - Have obtained consent from the cardholder to store their payment details - Provide `customer.id` or `customer.email` in the request You do not need to provide this field if `payment_type` is set to one of the following values: - `Installment` - `Recurring` - `Unscheduled` - `googlepay` object: Configuration options specific to Google Pay payments. - `store_payment_details` 'disabled' | 'enabled': Specifies whether you intend to store the cardholder's payment details. If you set this field to `enabled`, you must: - have obtained consent from the cardholder to store their payment details - provide a customer ID or email address in the request If the request's `payment_type` is set to one of the following values, you do not need to provide this field: - `Installment` - `Recurring` - `Unscheduled` - `recipient` PaymentInterfacesRecipient: Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions. - `dob` string, date: The recipient's date of birth, in the format `YYYY-MM-DD`. - `account_number` string: An identifier related to the primary recipient's account. For example, an IBAN, an internal account number, a phone number, or the first six and last four digits of the PAN. - `address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.