CHcheckout
Flow

Submit a Payment Session

Submit a payment attempt for a payment session.

This request works with the Flow <a href="https://checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/flowcomponent#handleSubmit(FlowComponent,_SubmitData)">handleSubmit</a> callback, where you can perform <a href="https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/dynamically-adjust-the-payment-amount">a customized payment submission</a>. You must send the unmodified response body as the response of the handleSubmit callback.

post/payment-sessions/{id}/submit

Request

Path parameters

idstring required

The Payment Sessions unique identifier

Example:ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ

Request body

session_datastring required

A unique token representing the additional customer data captured by Flow, as received from the <a href="https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/flowcomponent#handleSubmit(FlowComponent,_SubmitData)">handleSubmit</a> callback.

Do not log or store this value.

amountinteger

The payment amount. Provide a value of 0 to perform a card verification.

The amount must be provided in the <a href="https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value" target="blank">minor currency unit</a>.

currencystring

The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="blank">ISO currency code</a>.

success_urlstring uri

Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.

failure_urlstring uri

Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.

payment_type'Regular' | 'Recurring' | 'MOTO' | 'Installment' | 'Unscheduled'

Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.

referencestring

A reference you can use to identify the payment. For example, an order number.

  • For Amex payments, this must be at most 30 characters.
  • For Benefit payments, the reference must be a unique alphanumeric value.
  • For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.
ip_addressstring ipv4
processing_channel_idstring

The processing channel to use for the payment.

metadataPaymentSessionMetadata

Allows you to store additional information about a transaction with custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type string, number, and boolean within the metadata object. Arrays and objects are not supported.

You can provide up to 18 metadata fields per API call, but the value of each field must not exceed 255 characters in length.

You can also reference metadata properties in your custom rules for Fraud Detection. For example, $coupon_code = '1234'.

senderPaymentInterfacesSender

The sender type. If set to instrument, the sender information (name and address) will be retrieved from the payment instrument.

captureboolean

Specifies whether to capture the payment, if applicable.

capture_onstring date-time

A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, capture is automatically set to true.

Example request

{
  "amount": 1000,
  "currency": "USD",
  "billing": {
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    }
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure",
  "reference": "ORD-123A",
  "customer": {
    "email": "jia.tsang@example.com",
    "name": "Jia Tsang",
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "summary": {
      "registration_date": "2023-05-01T00:00:00.0000000",
      "first_transaction_date": "2023-07-01T00:00:00.0000000",
      "last_payment_date": "2023-08-01T00:00:00.0000000",
      "total_order_count": 15,
      "last_payment_amount": 500,
      "is_premium_customer": true,
      "is_returning_customer": true,
      "lifetime_value": 500
    }
  },
  "shipping": {
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    }
  },
  "items": [
    {
      "total_amount": 1000,
      "tax_amount": 1000,
      "discount_amount": 1000,
      "name": "Gold Necklace",
      "quantity": 1,
      "unit_price": 1000
    }
  ],
  "amount_allocations": [
    {
      "amount": 1,
      "reference": "ORD-123A",
      "commission": {
        "amount": 10,
        "percentage": 12.5
      }
    }
  ],
  "3ds": {
    "enabled": "false",
    "allow_upgrade": true,
    "exemption": "low_value"
  },
  "ip_address": "90.197.169.245",
  "recipient": {
    "dob": "1985-05-15T00:00:00.0000000",
    "account_number": "5555554444",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "first_name": "Jia",
    "last_name": "Tsang"
  },
  "metadata": {
    "coupon_code": "NY2018"
  },
  "capture": true,
  "capture_on": "2024-01-01T09:15:30.0000000+00:00",
  "processing": {
    "provision_network_token": true
  }
}

Response

Payment processed successfully.

OR

Example response

{
  "id": "pay_mbabizu24mvu3mela5njyhpit4"
}

Changes

No recorded changes to this operation across all 1 revision of this API.