Checkout.com API logo

Flow

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.

Request a Payment Session

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.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
Request Body schema: application/json
amount
required
integer >= 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
required
string = 3 characters

The three-letter ISO currency code.

required
object

The billing details.

success_url
required
string <uri> <= 1024 characters

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

failure_url
required
string <uri> <= 1024 characters

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

payment_type
string
Default: "Regular"

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

Enum: "Regular" "Recurring" "MOTO" "Installment" "Unscheduled"
object

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

reference
string <= 50 characters

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
string <= 100 characters

A description for the payment.

object

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

object

The shipping details

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.

object

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

object

Details about the payment instruction.

processing_channel_id
string^(pc)_(\w{26})$

The processing channel to use for the payment.

Array of objects [ 1 .. 1000 ] items

The line items in the order.

Array of objects [ 1 .. 50 ] items

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

object

Configures the risk assessment performed during payment processing.

display_name
string <= 255 characters

The merchant's display name.

metadata
object <= 18 properties

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
string
Default: "en-GB"

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

Enum: "ar" "da-DK" "de-DE" "el" "en-GB" "es-ES" "fi-FI" "fil-PH" "fr-FR" "hi-IN" "id-ID" "it-IT" "ja-JP" "ko-KR" "ms-MY" "nb-NO" "nl-NL" "pt-PT" "sv-SE" "th-TH" "vi-VN" "zh-CN" "zh-HK" "zh-TW"
Integrated authentication (object) or Third party authentication (object)

Information required for 3D Secure authentication payments.

object

The sender of the payment.

capture
boolean
Default: true

Specifies whether to capture the payment, if applicable.

capture_on
string <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.

expires_on
string <date-time>

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.

enabled_payment_methods
Array of strings

Specifies which payment method options to present to the customer.

The values in this field override any equivalent values in disabled_payment_methods.

Items Enum: "alipay_cn" "alipay_hk" "alma" "applepay" "bancontact" "benefit" "bizum" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "mbway" "mobilepay" "multibanco" "octopus" "p24" "paynow" "paypal" "plaid" "qpay" "remember_me" "sepa" "stcpay" "stored_card" "tabby" "tamara" "tng" "truemoney" "twint" "vipps" "wechatpay"
disabled_payment_methods
Array of strings

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.

Items Enum: "alipay_cn" "alipay_hk" "alma" "applepay" "bancontact" "benefit" "bizum" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "mbway" "mobilepay" "multibanco" "octopus" "p24" "paynow" "paypal" "plaid" "qpay" "remember_me" "sepa" "stcpay" "stored_card" "tabby" "tamara" "tng" "truemoney" "twint" "vipps" "wechatpay"
object

Configurations for payment method-specific settings.

object

Configuration for asynchronous retries.

ip_address
string <ipv4> <= 45 characters
Deprecated

The Customers IP address. Only IPv4 and IPv6 addresses are accepted.

Responses
201

A Payment Session.

401

Unauthorized (Empty Response).

422

Invalid data was sent.

429

Too many requests.

502

Bad gateway.

post/payment-sessions
Request samples
application/json
{
  • "amount": 1000,
  • "currency": "USD",
  • "payment_type": "Regular",
  • "billing": {
    },
  • "billing_descriptor": {
    },
  • "reference": "ORD-123A",
  • "description": "Payment for gold necklace",
  • "customer": {
    },
  • "shipping": {
    },
  • "recipient": {
    },
  • "processing": {
    },
  • "instruction": {
    },
  • "processing_channel_id": "string",
  • "items": [
    ],
  • "amount_allocations": [
    ],
  • "risk": {
    },
  • "display_name": "string",
  • "success_url": "https://example.com/payments/success",
  • "failure_url": "https://example.com/payments/failure",
  • "metadata": {
    },
  • "locale": "ar",
  • "3ds": {
    },
  • "sender": {
    },
  • "capture": true,
  • "capture_on": "2024-01-01T09:15:30Z",
  • "expires_on": "2024-01-01T09:15:30Z",
  • "enabled_payment_methods": [
    ],
  • "disabled_payment_methods": [
    ],
  • "payment_method_configuration": {
    },
  • "customer_retry": {
    },
  • "ip_address": "90.197.169.245"
}
Response samples
application/json
{}

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.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string (PaymentSessionId) = 30 characters ^(ps)_(\w{27})$

The Payment Sessions unique identifier

Example: ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ
Request Body schema: application/json
session_data
required
string

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
integer >= 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
string = 3 characters

The three-letter ISO currency code.

object

The billing details.

success_url
string <uri> <= 1024 characters

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

failure_url
string <uri> <= 1024 characters

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

payment_type
string
Default: "Regular"

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

Enum: "Regular" "Recurring" "MOTO" "Installment" "Unscheduled"
object

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

reference
string <= 50 characters

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.
object

The customer's details.

object

The shipping details

Array of objects [ 1 .. 1000 ] items

The line items in the order.

Integrated authentication (object) or Third party authentication (object)

Information required for 3D Secure authentication payments.

ip_address
string <ipv4> <= 45 characters
Deprecated

The Customer's IP address. Only IPv4 and IPv6 addresses are accepted.

object

Configurations for payment method-specific settings.

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.

object

Details about the payment instruction.

processing_channel_id
string^(pc)_(\w{26})$

The processing channel to use for the payment.

metadata
object <= 18 properties

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'.

object

The sender of the payment.

capture
boolean
Default: true

Specifies whether to capture the payment, if applicable.

capture_on
string <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.

Responses
201

Payment processed successfully.

202

Payment asynchronous or further action required.

401

Unauthorized (Empty Response).

422

Invalid data was sent.

429

Too many requests or duplicate request detected.

502

Bad gateway.

post/payment-sessions/{id}/submit
Request samples
application/json
{
  • "session_data": "string",
  • "amount": 1000,
  • "currency": "USD",
  • "billing": {
    },
  • "success_url": "https://example.com/payments/success",
  • "failure_url": "https://example.com/payments/failure",
  • "payment_type": "Regular",
  • "billing_descriptor": {
    },
  • "reference": "ORD-123A",
  • "customer": {
    },
  • "shipping": {
    },
  • "items": [
    ],
  • "3ds": {
    },
  • "ip_address": "90.197.169.245",
  • "payment_method_configuration": {
    },
  • "recipient": {
    },
  • "instruction": {
    },
  • "processing_channel_id": "string",
  • "metadata": {
    },
  • "sender": {
    },
  • "capture": true,
  • "capture_on": "2024-01-01T09:15:30Z"
}
Response samples
application/json
{
  • "id": "pay_mbabizu24mvu3mela5njyhpit4",
  • "status": "Approved",
  • "type": "alipay_cn"
}

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.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
Request Body schema: application/json
session_data
required
string

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
required
integer >= 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
required
string = 3 characters

The three-letter ISO currency code.

required
object

The billing details.

success_url
required
string <uri> <= 1024 characters

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

failure_url
required
string <uri> <= 1024 characters

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

payment_type
string
Default: "Regular"

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

Enum: "Regular" "Recurring" "MOTO" "Installment" "Unscheduled"
object

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

reference
string <= 50 characters

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
string <= 100 characters

A description for the payment.

object

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

object

The shipping details

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.

object

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

object

Details about the payment instruction.

processing_channel_id
string^(pc)_(\w{26})$

The processing channel to use for the payment.

Array of objects [ 1 .. 1000 ] items

The line items in the order.

Array of objects [ 1 .. 50 ] items

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

object

Configures the risk assessment performed during payment processing.

display_name
string <= 255 characters

The merchant's display name.

metadata
object <= 18 properties

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
string
Default: "en-GB"

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

Enum: "ar" "da-DK" "de-DE" "el" "en-GB" "es-ES" "fi-FI" "fil-PH" "fr-FR" "hi-IN" "id-ID" "it-IT" "ja-JP" "ko-KR" "ms-MY" "nb-NO" "nl-NL" "pt-PT" "sv-SE" "th-TH" "vi-VN" "zh-CN" "zh-HK" "zh-TW"
Integrated authentication (object) or Third party authentication (object)

Information required for 3D Secure authentication payments.

object

The sender of the payment.

capture
boolean
Default: true

Specifies whether to capture the payment, if applicable.

capture_on
string <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.

Responses
201

Payment processed successfully.

202

Payment asynchronous or further action required.

401

Unauthorized (Empty Response).

422

Invalid data was sent.

429

Too many requests or duplicate request detected.

502

Bad gateway.

post/payment-sessions/complete
Request samples
application/json
{
  • "session_data": "string",
  • "amount": 1000,
  • "currency": "USD",
  • "payment_type": "Regular",
  • "billing": {
    },
  • "billing_descriptor": {
    },
  • "reference": "ORD-123A",
  • "description": "Payment for gold necklace",
  • "customer": {
    },
  • "shipping": {
    },
  • "recipient": {
    },
  • "processing": {
    },
  • "instruction": {
    },
  • "processing_channel_id": "string",
  • "items": [
    ],
  • "amount_allocations": [
    ],
  • "risk": {
    },
  • "display_name": "string",
  • "success_url": "https://example.com/payments/success",
  • "failure_url": "https://example.com/payments/failure",
  • "metadata": {
    },
  • "locale": "ar",
  • "3ds": {
    },
  • "sender": {
    },
  • "capture": true,
  • "capture_on": "2024-01-01T09:15:30Z"
}
Response samples
application/json
{
  • "id": "pay_mbabizu24mvu3mela5njyhpit4",
  • "status": "Approved",
  • "type": "alipay_cn",
  • "payment_session_id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  • "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
}
➔ Next to Payment Setups