CHcheckout
Flow

Request a Payment Session with Payment

Create a payment session and submit a payment attempt for it.

The values you provide in the request will be used to determine the payment methods available to Flow. Some payment methods may require you to provide specific values for certain fields. Refer to our <a href="https://www.checkout.com/docs/payments/add-payment-methods">documentation</a> for more information.

This request works with the advanced Flow integration, where <a href="https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session">you do not need to create a payment session for initializing Flow</a>. You must send the unmodified response body as the response of the <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.

post/payment-sessions/complete

Request

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 required

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 required

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

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.

authorization_type'Final' | 'Estimated'

The authorization type.

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.
descriptionstring

A description for the payment.

processing_channel_idstring

The processing channel to use for the payment.

display_namestring

The merchant's display name.

success_urlstring uri required

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

failure_urlstring uri required

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

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'.

locale'ar' | 'da-DK' | 'de-DE' | 'el' | 'en-GB' | 'es-ES' | 'fi-FI' | 'fil-PH' | 'fr-FR' | 'hi-IN' | 'id-ID' | 'it-IT' | 'ja-JP' | 'ko-KR' | 'ms-MY' | 'nb-NO' | 'nl-NL' | 'pt-PT' | 'sv-SE' | 'th-TH' | 'vi-VN' | 'zh-CN' | 'zh-HK' | 'zh-TW'

Creates a translated version of the page in the specified language.

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",
  "authorization_type": "Estimated",
  "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"
    }
  },
  "reference": "ORD-123A",
  "description": "Payment for gold necklace",
  "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"
    }
  },
  "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"
  },
  "processing": {
    "shipping_amount": 300,
    "tax_amount": 3000,
    "locale": "en-US",
    "airline_data": [
      {
        "ticket": {
          "number": "045-21351455613",
          "issue_date": "2023-05-20T00:00:00.0000000",
          "issuing_carrier_code": "AI",
          "travel_package_indicator": "B",
          "travel_agency_name": "World Tours",
          "travel_agency_code": "01"
        },
        "passenger": [
          {
            "first_name": "John",
            "last_name": "White",
            "date_of_birth": "1990-05-26T00:00:00.0000000",
            "address": {
              "country": "US"
            }
          }
        ],
        "flight_leg_details": [
          {
            "flight_number": "101",
            "carrier_code": "BA",
            "class_of_travelling": "J",
            "departure_airport": "LHR",
            "departure_date": "2023-06-19T00:00:00.0000000",
            "departure_time": "15:30",
            "arrival_airport": "LAX",
            "stop_over_code": "x",
            "fare_basis_code": "SPRSVR"
          }
        ]
      }
    ],
    "accommodation_data": [
      {
        "name": "The Sea View Hotel",
        "booking_reference": "HOTEL123",
        "check_in_date": "2023-06-20T00:00:00.0000000",
        "check_out_date": "2023-06-23T00:00:00.0000000",
        "address": {
          "address_line1": "123 Beach Road",
          "zip": "10001"
        },
        "state": "FL",
        "country": "USA",
        "city": "Los Angeles",
        "number_of_rooms": 2,
        "guests": [
          {
            "first_name": "Jane",
            "last_name": "Doe",
            "date_of_birth": "1985-07-14T00:00:00.0000000"
          }
        ],
        "room": [
          {
            "rate": "70",
            "number_of_nights_at_room_rate": "3"
          }
        ]
      }
    ],
    "order_id": "123456789",
    "surcharge_amount": 200,
    "shipping_tax_amount": 100,
    "affiliate_url": "www.mycrypto.com",
    "original_order_amount": 10,
    "receipt_id": "10",
    "line_of_business": "Flights",
    "provision_network_token": true,
    "reconciliation_id": "4123495123",
    "aggregator": {
      "sub_merchant_id": "9cf70789ba90123",
      "aggregator_id_visa": "10012345",
      "aggregator_id_mc": "00000123456"
    }
  },
  "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
      }
    }
  ],
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure",
  "metadata": {
    "coupon_code": "NY2018"
  },
  "3ds": {
    "enabled": "false",
    "allow_upgrade": true,
    "exemption": "low_value"
  },
  "capture": true,
  "capture_on": "2024-01-01T09:15:30.0000000+00:00",
  "payment_plan": {
    "amount_variability": "Variable",
    "days_between_payments": 28,
    "total_number_of_payments": 5,
    "current_payment_number": 3,
    "expiry": "20251031",
    "name": "Subscription 1234",
    "start_date": "20260507",
    "amount": 1234
  }
}

Response

Payment processed successfully.

OR

Example response

{
  "id": "pay_mbabizu24mvu3mela5njyhpit4",
  "payment_session_id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
}

Changes

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