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 documentation for more information.

This request works with the advanced Flow integration, where you do not need to create a payment session for initializing Flow. You must send the unmodified response body as the response of the handleSubmit callback.

Body·
application/json
  • Type: object
    • session_data
      Type: 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
      Type: integer ·
      min:  
      0
      required

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

      The amount must be provided in the minor currency unit.

    • currency
      Type: string ·
      min length:  
      3
      max length:  
      3
      required

      The three-letter ISO currency code.

    • billing
      Type: object ·
      required

      The billing details.

    • success_url
      Type: string ·
      max length:  
      1024      Format: uri
      required

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

    • failure_url
      Type: string ·
      max length:  
      1024      Format: uri
      required

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

    • payment_type
      Type: string · enum

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

      values
      • Regular
      • Recurring
      • MOTO
      • Installment
      • Unscheduled
    • authorization_type
      Type: string enum

      The authorization type.

      values
      • Final
      • Estimated
    • billing_descriptor
      Type: object ·

      A description of the purchase, which is displayed on the customer's statement.

    • reference
      Type: string ·
      max length:  
      50

      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.
    • description
      Type: string
      max length:  
      100

      A description for the payment.

    • customer
      Type: object ·

      The customer's details. Required if source.type is tamara.

    • shipping
      Type: object ·

      The shipping details

    • recipient
      Type: object ·

      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.

    • processing
      Type: object ·

      Use the processing object to influence or override the data sent during card processing

    • instruction
      Type: object

      Details about the payment instruction.

    • processing_channel_id
      Type: string · Pattern: ^(pc)_(\w{26})$

      The processing channel to use for the payment.

    • items
      Type: array object[] · 1…1000

      The line items in the order.

    • amount_allocations
      Type: array object[] 1…50

      The sub-entities that the payment is being processed on behalf of.

      The sub-entities that the payment is being processed on behalf of.

    • risk
      Type: object

      Configures the risk assessment performed during payment processing.

    • display_name
      Type: string
      max length:  
      255

      The merchant's display name.

    • metadata
      Type: object ·

      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
      Type: string enum

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

      values
      • ar
      • da-DK
      • de-DE
      • el
      • en-GB
    • 3ds
    • sender
      Type: object ·

      The sender of the payment.

      • type
        Discriminator
        enum
        const:  
        individual
        required

        The type of sender

        values
        • individual
      • first_name
        Type: string
        max length:  
        50
        required

        The sender's first name

      • last_name
        Type: string
        max length:  
        50
        required

        The sender's last name

      • reference
        Type: string

        The sender's reference for the payout

      • dob
        Type: string
        max length:  
        10        Format: date
        deprecated

        This field is deprecated. Use date_of_birth instead.

        The sender's date of birth, in the format yyyy-mm-dd.

      • date_of_birth
        Type: string
        max length:  
        10        Format: date

        The sender's date of birth, in the format yyyy-mm-dd.

      • address
        Type: object ·

        The sender's address

      • identification
        Type: object
    • capture
      Type: boolean ·

      Specifies whether to capture the payment, if applicable.

    • capture_on
      Type: string · Format: 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.

    • payment_plan
      Type: object ·

      The information to process a recurring payment request. To be used when the payment_type is Recurring.

Responses
  • application/json
  • application/json
  • 401

    Unauthorized (Empty Response).

  • application/problem+json; charset=utf-8
  • application/json
  • 502

    Bad gateway.

Request Example for post/payment-sessions/complete
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/payment-sessions/complete' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "session_data": "",
  "amount": 1000,
  "currency": "USD",
  "payment_type": "Regular",
  "authorization_type": "Estimated",
  "billing": {
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    }
  },
  "billing_descriptor": {
    "name": "",
    "city": "",
    "reference": ""
  },
  "reference": "ORD-123A",
  "description": "Payment for gold necklace",
  "customer": {
    "email": "jia.tsang@example.com",
    "name": "Jia Tsang",
    "id": "",
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "tax_number": "",
    "summary": {
      "registration_date": "2023-05-01",
      "first_transaction_date": "2023-07-01",
      "last_payment_date": "2023-08-01",
      "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",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    }
  },
  "recipient": {
    "dob": {},
    "account_number": "5555554444",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "first_name": "Jia",
    "last_name": "Tsang"
  },
  "processing": {
    "aft": true,
    "discount_amount": 0,
    "shipping_amount": 300,
    "tax_amount": 3000,
    "invoice_id": "",
    "brand_name": "",
    "locale": "en-US",
    "partner_customer_risk_data": {
      "key": "",
      "value": ""
    },
    "custom_payment_method_ids": [
      ""
    ],
    "airline_data": [
      {
        "ticket": {
          "number": "045-21351455613",
          "issue_date": "2023-05-20",
          "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-26",
            "address": {
              "country": "US"
            }
          }
        ],
        "flight_leg_details": [
          {
            "flight_number": "101",
            "carrier_code": "BA",
            "class_of_travelling": "J",
            "departure_airport": "LHR",
            "departure_date": "2023-06-19",
            "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-20",
        "check_out_date": "2023-06-23",
        "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-14"
          }
        ],
        "room": [
          {
            "rate": "70",
            "number_of_nights_at_room_rate": "3"
          }
        ]
      }
    ],
    "order_id": "123456789",
    "surcharge_amount": 200,
    "duty_amount": 0,
    "shipping_tax_amount": 100,
    "affiliate_id": "",
    "affiliate_url": "www.mycrypto.com",
    "purchase_country": "",
    "merchant_initiated_reason": "Delayed_charge",
    "campaign_id": 1,
    "original_order_amount": 10,
    "receipt_id": "10",
    "merchant_callback_url": "",
    "line_of_business": "Flights",
    "pan_preference": "fpan",
    "provision_network_token": true,
    "reconciliation_id": "4123495123",
    "aggregator": {
      "sub_merchant_id": "9cf70789ba90123",
      "aggregator_id_visa": "10012345",
      "aggregator_id_mc": "00000123456"
    }
  },
  "instruction": {
    "purpose": "donations"
  },
  "processing_channel_id": "",
  "items": [
    {
      "reference": "",
      "commodity_code": "",
      "unit_of_measure": "",
      "total_amount": 1000,
      "tax_amount": 1000,
      "discount_amount": 1000,
      "url": "",
      "image_url": "",
      "name": "Gold Necklace",
      "quantity": 1,
      "unit_price": 1000
    }
  ],
  "amount_allocations": [
    {
      "id": "",
      "amount": 1,
      "reference": "ORD-123A",
      "commission": {
        "amount": 10,
        "percentage": 12.5
      }
    }
  ],
  "risk": {
    "enabled": false
  },
  "display_name": "",
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure",
  "metadata": {
    "coupon_code": "NY2018"
  },
  "locale": "en-GB",
  "3ds": {
    "enabled": "false",
    "challenge_indicator": "no_preference",
    "allow_upgrade": true,
    "exemption": "low_value"
  },
  "sender": {},
  "capture": true,
  "capture_on": "2024-01-01T09:15:30Z",
  "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
  }
}'

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

Payment processed successfully.