CHcheckout
Flow

Request a Payment Session

Creates a payment session.

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.

You must supply the unmodified response body when you <a href="https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/get-started-with-flow#Initialize_and_mount_Flow_">initialize Flow</a>.

post/payment-sessions

Request

Request body

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.

expires_onstring date-time

A timestamp specifying when the PaymentSession should expire, as an ISO 8601 code. If no value is provided, expiry is set to 24 hours after the PaymentSession is created. You cannot set the session expiry to more than 60 days after the PaymentSession is created.

enabled_payment_methodsPaymentInterfacesPaymentMethodEnum[]
disabled_payment_methodsPaymentInterfacesPaymentMethodEnum[]
ip_addressstring ipv4

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
  },
  "expires_on": "2024-01-01T09:15:30.0000000+00:00",
  "customer_retry": {
    "max_attempts": 2
  },
  "ip_address": "90.197.169.245"
}

Response

A Payment Session.

idstring required

The Payment Sessions unique identifier

payment_session_tokenstring required

A unique token representing the payment session, which you must provide when you initialize Flow.

Do not log or store this value.

payment_session_secretstring required

The secret used by Flow to authenticate payment session requests.

Do not log or store this value.

Example response

{
  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
    }
  }
}

Changes

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