Submit a Payment Session

​

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
    Type: string ·
    min length:  
    30
    max length:  
    30    Pattern: ^(ps)_(\w{27})$
    required

    The Payment Sessions unique identifier

Body·
application/json
  • 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

    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

    The three-letter ISO currency code.

  • billing
    Type: object ·

    The billing details.

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

    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

    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
  • 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.
  • customer
    Type: object ·

    The customer's details.

  • shipping
    Type: object ·

    The shipping details

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

    The line items in the order.

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/{id}/submit
curl 'https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ/submit' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "session_data": "",
  "amount": 1000,
  "currency": "USD",
  "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"
    }
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure",
  "payment_type": "Regular",
  "billing_descriptor": {
    "name": "",
    "city": "",
    "reference": ""
  },
  "reference": "ORD-123A",
  "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"
    }
  },
  "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
      }
    }
  ],
  "3ds": {
    "enabled": "false",
    "challenge_indicator": "no_preference",
    "allow_upgrade": true,
    "exemption": "low_value"
  },
  "payment_method_configuration": {
    "applepay": {
      "store_payment_details": "disabled"
    },
    "card": {
      "store_payment_details": "disabled"
    },
    "googlepay": {
      "store_payment_details": "disabled"
    }
  },
  "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"
  },
  "instruction": {
    "purpose": "donations"
  },
  "processing_channel_id": "",
  "metadata": {
    "coupon_code": "NY2018"
  },
  "sender": {},
  "capture": true,
  "capture_on": "2024-01-01T09:15:30Z",
  "processing": {
    "pan_preference": "fpan",
    "provision_network_token": true
  }
}'

{
  "id": "pay_mbabizu24mvu3mela5njyhpit4",
  "status": "Approved",
  "type": "card"
}

Payment processed successfully.