A Flow payment session contains the information required to display relevant payment methods and handle the payment flow.
To enable access to Flow, contact your solutions engineer or request support.
A Flow payment session contains the information required to display relevant payment methods and handle the payment flow.
To enable access to Flow, contact your solutions engineer or request support.
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 documentation for more information.
You must supply the unmodified response body when you initialize Flow.
The payment amount. Provide a value of 0 to perform a card verification.
The amount must be provided in the minor currency unit.
The three-letter ISO currency code.
The billing details.
Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.
Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.
Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.
The authorization type.
A description of the purchase, which is displayed on the customer's statement.
A reference you can use to identify the payment. For example, an order number.
A description for the payment.
The customer's details. Required if source.type is tamara.
The shipping details
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.
Use the processing object to influence or override the data sent during card processing
Details about the payment instruction.
Pattern: ^(pc)_(\w{26})$The processing channel to use for the payment.
The line items in the order.
The sub-entities that the payment is being processed on behalf of.
The sub-entities that the payment is being processed on behalf of.
Configures the risk assessment performed during payment processing.
The merchant's display name.
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'.
Creates a translated version of the page in the specified language.
The sender of the payment.
The type of sender
The sender's first name
The sender's last name
The sender's reference for the payout
This field is deprecated. Use date_of_birth instead.
The sender's date of birth, in the format yyyy-mm-dd.
The sender's date of birth, in the format yyyy-mm-dd.
The sender's address
Specifies whether to capture the payment, if applicable.
A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, capture is automatically set to true.
The information to process a recurring payment request. To be used when the payment_type is Recurring.
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.
Specifies which payment method options to present to the customer.
The values in this field override any equivalent values in disabled_payment_methods.
Specifies which payment method options to not present to the customer.
If you specify the same payment method in this field and in enabled_payment_methods, the disabled_payment_methods value will be overridden.
Any payment method options not explicitly specified in this field will be presented to the customer by default.
Configurations for payment method-specific settings.
Configuration for asynchronous retries.
The Customers IP address. Only IPv4 and IPv6 addresses are accepted.
Unauthorized (Empty Response).
Bad gateway.
curl 'https://{prefix}.api.sandbox.checkout.com/payment-sessions' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--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
},
"expires_on": "2024-01-01T09:15:30Z",
"enabled_payment_methods": [
"card",
"applepay",
"googlepay"
],
"disabled_payment_methods": [
"eps",
"ideal",
"knet"
],
"payment_method_configuration": {
"applepay": {
"account_holder": {},
"total_type": "final"
},
"card": {
"account_holder": {}
},
"googlepay": {
"account_holder": {},
"total_price_status": "final"
},
"stored_card": {
"customer_id": "",
"instrument_ids": [
""
],
"default_instrument_id": ""
}
},
"customer_retry": {
"max_attempts": 2
}
}'
{
"id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
"payment_session_token": "string",
"payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
}
}
}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.
Pattern: ^(ps)_(\w{27})$The Payment Sessions unique identifier
The payment amount. Provide a value of 0 to perform a card verification.
The amount must be provided in the minor currency unit.
The three-letter ISO currency code.
The billing details.
Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.
Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.
Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.
A description of the purchase, which is displayed on the customer's statement.
A reference you can use to identify the payment. For example, an order number.
The customer's details.
The shipping details
The line items in the order.
Unauthorized (Empty Response).
Bad gateway.
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"
}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.
The payment amount. Provide a value of 0 to perform a card verification.
The amount must be provided in the minor currency unit.
The three-letter ISO currency code.
The billing details.
Overrides the default success redirect URL configured on your account, for payment methods that require a redirect.
Overrides the default failure redirect URL configured on your account, for payment methods that require a redirect.
Must be specified for card-not-present (CNP) payments. For example, a recurring mail order / telephone order (MOTO) payment.
The authorization type.
A description of the purchase, which is displayed on the customer's statement.
A reference you can use to identify the payment. For example, an order number.
A description for the payment.
The customer's details. Required if source.type is tamara.
The shipping details
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.
Use the processing object to influence or override the data sent during card processing
Details about the payment instruction.
Pattern: ^(pc)_(\w{26})$The processing channel to use for the payment.
The line items in the order.
The sub-entities that the payment is being processed on behalf of.
The sub-entities that the payment is being processed on behalf of.
Configures the risk assessment performed during payment processing.
The merchant's display name.
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'.
Creates a translated version of the page in the specified language.
The sender of the payment.
The type of sender
The sender's first name
The sender's last name
The sender's reference for the payout
This field is deprecated. Use date_of_birth instead.
The sender's date of birth, in the format yyyy-mm-dd.
The sender's date of birth, in the format yyyy-mm-dd.
The sender's address
Specifies whether to capture the payment, if applicable.
A timestamp specifying when to capture the payment, as an ISO 8601 code. If a value is provided, capture is automatically set to true.
The information to process a recurring payment request. To be used when the payment_type is Recurring.
Unauthorized (Empty Response).
Bad gateway.
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"
}