CHcheckout
Payment Context

Request a Payment Context

Send a Payment Context request. <br><br><b>Note</b>: Successful Payment Context requests will always return a 201 response.

Effective August 2026, Payment Context is no longer supported for new integrations. New integration requests return a 405 Method Not Allowed response. For new integrations, call the Create a Payment Setup endpoint instead.

post/payment-contexts

Request

Headers

Cko-Idempotency-Keystring

An optional idempotency key for safely retrying payment requests

Request body

amountinteger required

The Payment Context Payment amount. The amount must be provided in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" 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'

"Recurring" must be specified if the payment is paid in multiple installments.

captureboolean

Whether to capture the later payment (if applicable).

processing_channel_idstring

The processing channel to be used for the payment.

referencestring

A reference you can later use to identify this Payment Context, such as an order number.<br>Can only be alphanumeric and must be unique for Benefit.<br>For Amex, the string limit is 30 characters.

descriptionstring

A description of the Payment Context.

success_urlstring uri

For redirect payment methods, this overrides the default success redirect URL configured on your account.

failure_urlstring uri

For redirect payment methods, this overrides the default failure redirect URL configured on your account.

metadataobject

A set of key-value pairs store additional information about a transaction. You can send custom fields and up to five user-defined fields, which can be used for reporting purposes. You can supply fields of type

  • string
  • number
  • boolean

Arrays and objects are not supported.

You can provide up to 20 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.

Example request

{
  "source": {
    "type": "klarna"
  },
  "amount": 6540,
  "currency": "USD",
  "payment_type": "Recurring",
  "capture": true,
  "customer": {
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "email": "card.success@tabby.ai",
    "name": "string",
    "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
    }
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "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"
    },
    "from_address_zip": "123456",
    "timeframe": "SameDay",
    "method": "BillingAddress",
    "delay": 5
  },
  "processing": {
    "plan": {
      "type": "MERCHANT_INITIATED_BILLING"
    },
    "discount_amount": 5,
    "shipping_amount": 300,
    "tax_amount": 3000,
    "brand_name": "Acme Corporation",
    "locale": "en-US",
    "shipping_preference": "set_provided_address",
    "user_action": "pay_now",
    "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"
          }
        ],
        "property_phone": [
          {
            "country_code": "44",
            "number": "7123456789"
          }
        ],
        "customer_service_phone": [
          {
            "country_code": "44",
            "number": "7123456789"
          }
        ]
      }
    ]
  },
  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  "reference": "ORD-5023-4E89",
  "description": "Set of 3 masks",
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/fail",
  "items": [
    {
      "name": "Test item",
      "quantity": 2,
      "unit_price": 50,
      "reference": "858818ac",
      "total_amount": 29000,
      "tax_rate": 2000,
      "tax_amount": 1000,
      "discount_amount": 1000
    }
  ],
  "metadata": {
    "coupon_code": "NY2018"
  }
}

Response

Payment Context Created.

idstring required

Payment Context's unique identifier.

amountinteger

The payment amount.

processed_onstring date-time required

Read-only UTC timestamp, automatically assigned by us

statusstring

The status of the payment context.

response_codestring

The gateway response code.

response_summarystring

The gateway response summary.

Example response

{
  "id": "pct_y3oqhf46pyzuxjbcn2giaqnb44",
  "status": "Pending",
  "response_code": "2000",
  "response_summary": "Rejected",
  "available_payment_types": [
    {
      "payment_plan": {
        "days_between_payments": 28,
        "total_number_of_payments": 5,
        "current_payment_number": 3,
        "expiry": "20251031",
        "name": "Subscription 1234",
        "start_date": "20260507",
        "amount": 1234
      }
    }
  ],
  "unavailable_payment_types": [
    {
      "payment_plan": {
        "days_between_payments": 28,
        "total_number_of_payments": 5,
        "current_payment_number": 3,
        "expiry": "20251031",
        "name": "Subscription 1234",
        "start_date": "20260507",
        "amount": 1234
      }
    }
  ],
  "partner_metadata": {
    "order_id": "test_order_123",
    "customer_id": "cus_123",
    "session_id": "feb0096d-8486-400d-89fa-2fa716b4521f",
    "client_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjgyMzA1ZWJjLWI4MTEtMzYzNy1hYTRjLTY2ZWNhMTg3NGYzZCJ9.eyJzZXNzaW9uX2lkIjoiY2RiNDI0MGQtMTdkYy01MjJkLWJlYjEtYjAyYjRlMzllYTdhIiwiYmFzZV91cmwiOiJodHRwczovL2pzLnBsYXlncm91bmQua2xhcm5hLmNvbS9ldS9rcCIsImRlc2lnbiI6ImtsYXJuYSIsImxhbmd1YWdlIjoiZW4iLCJwdXJjaGFzZV9jb3VudHJ5IjoiREUiLCJlbnZpcm9ubWVudCI6InBsYXlncm91bmQiLCJtZXJjaGFudF9uYW1lIjoiQ2hlY2tvdXQuY29tIiwic2Vzc2lvbl90eXBlIjoiUEFZTUVOVFMiLCJjbGllbnRfZXZlbnRfYmFzZV91cmwiOiJodHRwczovL2V1LnBsYXlncm91bmQua2xhcm5hZXZ0LmNvbSIsInNjaGVtZSI6dHJ1ZSwiZXhwZXJpbWVudHMiOlt7Im5hbWUiOiJrcC1jbGllbnQtb25lLXB1cmNoYXNlLWZsb3ciLCJ2YXJpYXRlIjoidmFyaWF0ZS0xIn0seyJuYW1lIjoia3AtY2xpZW50LXV0b3BpYS1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwYy0xay1zZXJ2aWNlIiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtc3RhdGljLXdpZGdldCIsInZhcmlhdGUiOiJpbmRleCIsInBhcmFtZXRlcnMiOnsiZHluYW1pYyI6InRydWUifX0seyJuYW1lIjoiaW4tYXBwLXNkay1uZXctaW50ZXJuYWwtYnJvd3NlciIsInBhcmFtZXRlcnMiOnsidmFyaWF0ZV9pZCI6Im5ldy1pbnRlcm5hbC1icm93c2VyLWVuYWJsZSJ9fSx7Im5hbWUiOiJrcC1jbGllbnQtdXRvcGlhLXNkay1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtd2Vidmlldy1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImluLWFwcC1zZGstY2FyZC1zY2FubmluZyIsInBhcmFtZXRlcnMiOnsidmFyaWF0ZV9pZCI6ImNhcmQtc2Nhbm5pbmctZW5hYmxlIn19XSwicmVnaW9uIjoiZXUiLCJvcmRlcl9hbW91bnQiOjIwMDAsIm9mZmVyaW5nX29wdHMiOjAsIm9vIjoiY3ciLCJ2ZXJzaW9uIjoidjEuMTAuMC0xNTkwLWczZWJjMzkwNyJ9.ZxThQVo5e0Fck1vwOQ-WWAr7Zw-dsiEhjd3CW-E5p8atUhnBhrzIs6WCBeOOv3ci2VvpykVnDw2qycCTA-7TpTq1wn_kPxxixDQnYJYJzrZMoUhPLZo5pfy2a1S_t2owEQks0THRzu2wRlZwCN4ewDnVqsut60X4r3B92cJENIDtEC4Fs55CjFEmYUtsLXSspNLKvpZe2zg4O_M5yjH7XsBs5YJalZLexf4545G5vJrmVHgiA322mbgWC7BH0IU1A-ql5sFvs190_cjGaLsAvrkh9CVczUPy3X-jr3A5z1YRVfywPpvwKFWL8GZtgrdUZmgiU5_8ZZLkEPzrSucHrQ"
  }
}

Changes

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