Payment Context

Request a Payment Context

Send a Payment Context request.

Note: Successful Payment Context requests will always return a 201 response.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

header Parameters

Cko-Idempotency-Key

string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json

required	object (PaymentContextSource) The source of the payment.
currency required	string = 3 characters The three-letter ISO currency code.
amount required	integer >= 0 The Payment Context Payment amount. The amount must be provided in the minor currency unit.
payment_type	string Default: "Regular" "Recurring" must be specified if the payment is paid in multiple installments. Enum: "Regular" "Recurring"
capture	boolean Default: true Whether to capture the later payment (if applicable).
	object (PaymentContextDetailsCustomer) The customer details. Required if `source.type` is `StcPay` or `Tabby`.
	object (Shipping) The shipping details.
	object Use the processing object to influence or override the data during the payment processing.
processing_channel_id	string^(pc)_(\w{26})$ The processing channel to be used for the payment.
reference	string <= 50 characters A reference you can later use to identify this Payment Context, such as an order number. Can only be alphanumeric and must be unique for Benefit. For Amex, the string limit is 30 characters.
description	string <= 100 characters A description of the Payment Context.
success_url	string <uri> <= 1024 characters For redirect payment methods, this overrides the default success redirect URL configured on your account.
failure_url	string <uri> <= 1024 characters For redirect payment methods, this overrides the default failure redirect URL configured on your account.
	Array of objects (PaymentContextItems) The order's line items. Required for Klarna payments.
metadata	object 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.

Responses

201

Payment Context Created.

401

Unauthorized

422

Invalid data was sent.

429

Too many requests or duplicate request detected.

502

Bad gateway

post/payment-contexts

Request samples

Payload
curl
Java
C#
Python

application/json

{"source": {"type": "paypal"
},
"amount": 6540,
"currency": "USD",
"payment_type": "Recurring",
"capture": true,
"customer": {"phone": {"country_code": "+1",
"number": "415 555 2671",
"phone_verified": true
},
"email": "card.success@tabby.ai",
"name": "string",
"email_verified": true,
"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
}
},
"shipping": {"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"address": {"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"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",
"skip_shipping_address": true,
"immutable_shipping_address": true
},
"discount_amount": 5,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "Acme Corporation",
"locale": "en-US",
"shipping_preference": "set_provided_address",
"user_action": "pay_now",
"partner_customer_risk_data": {"key": "string",
"value": "string"
},
"custom_payment_method_ids": ["string"
],
"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"
}
],
"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": [{"type": "string",
"name": "Test item",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string"
}
],
"metadata": {"coupon_code": "NY2018"
}
}

Response samples

application/json

{"id": "pct_y3oqhf46pyzuxjbcn2giaqnb44",
"amount": 0,
"processed_on": "2019-08-24T14:15:22Z",
"status": "Pending",
"response_code": "2000",
"response_summary": "Rejected",
"available_payment_types": [{"payment_type": "Regular",
"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_type": "Regular",
"rejection_reason": "string",
"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
},
"description": "string"
}
],
"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"
},
"_links": {"self": {"href": "https://{prefix}.api.checkout.com/payment-contexts/pct_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}

Get Payment Context details

Returns all the Payment Context details.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

required

string (PaymentContextId) = 30 characters ^(pct)_(\w{26})$

Payment Context's unique identifier.

Example: pct_y3oqhf46pyzuxjbcn2giaqnb44

Responses

200

Payment Context retrieved successfully.

401

Unauthorized

404

Payment Context not found.

get/payment-contexts/{id}

Request samples

curl
Java
C#
Python

Response samples

application/json

{"status": "Approved",
"payment_request": {"source": {"type": "paypal"
},
"amount": 6540,
"currency": "USD",
"payment_type": "Recurring",
"capture": true,
"customer": {"email": "johnsmith@example.com",
"name": "John Smith"
},
"shipping": {"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"address": {"address_line1": "123 High St.",
"address_line2": "Flat 456",
"city": "London",
"state": "str",
"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",
"skip_shipping_address": true,
"immutable_shipping_address": true
},
"discount_amount": 5,
"shipping_amount": 300,
"tax_amount": 3000,
"invoice_id": "string",
"brand_name": "Acme Corporation",
"locale": "en-US",
"shipping_preference": "set_provided_address",
"user_action": "pay_now",
"partner_customer_risk_data": {"key": "string",
"value": "string"
},
"custom_payment_method_ids": ["string"
],
"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": null
}
}
],
"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"
}
],
"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": [{"type": "string",
"name": "Test item",
"quantity": 2,
"unit_price": 50,
"reference": "858818ac",
"total_amount": 29000,
"tax_rate": 2000,
"tax_amount": 1000,
"discount_amount": 1000,
"url": "string",
"image_url": "string"
}
],
"metadata": {"coupon_code": "NY2018"
}
},
"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"
}
}

➔ Next to Payment Methods