Checkout.com API logo

Payment Setups

The Payment Setup API enables you to simplify the management of complex payment flows that cover multiple payment methods.

For more information, see Accept a payment using the Payment Setup API.

Create a Payment Setup

Beta

Creates a Payment Setup.

To maximize the information available to the payment setup, create a Payment Setup as early as possible in the customer's journey. For example, create it the first time they land on the basket page.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
Request Body schema: application/json
required
processing_channel_id
required
string^(pc)_(\w{26})$

The processing channel to use for the payment.

amount
required
number

The payment amount, in the minor currency unit.

currency
required
string

The currency of the payment, as a three-letter ISO currency code.

payment_type
string
Default: "Regular"

The type of payment.

You must provide this field for card payments in which the cardholder is not present. For example, if the transaction is a recurring payment, or a mail order/telephone order (MOTO) payment.

Enum: "Regular" "Recurring" "MOTO" "Installment" "PayLater" "Unscheduled"
reference
string <= 80 characters

A reference you can use to identify the payment. For example, an order number.

description
string <= 100 characters

A description of the payment.

object

The payment methods that are enabled on your account and available for use.

object

Settings for the Payment Setup.

object

The customer's details.

object

The customer's order details.

object (PaymentSetupBilling)

The billing details for the payment.

object

Industry-specific information.

Responses
200

Payment Setup created.

400

The request is invalid. See the response body for details.

401

Authentication failed. Provide a valid API key or access token.

403

You do not have permission to create a Payment Setup.

422

One or more fields failed validation. See the response body for details.

post/payments/setups
Request samples
application/json
{
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount": 10000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "reference": "REF-0987-475",
  • "description": "Set of 3 t-shirts",
  • "payment_methods": {
    },
  • "settings": {},
  • "customer": {
    },
  • "order": {
    },
  • "billing": {
    },
  • "industry": {
    }
}
Response samples
application/json
{
  • "id": "string",
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount": 10000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "reference": "REF-0987-475",
  • "description": "Set of 3 t-shirts",
  • "payment_methods": {
    },
  • "available_payment_methods": [
    ],
  • "settings": {},
  • "customer": {
    },
  • "order": {
    },
  • "billing": {
    },
  • "industry": {
    }
}

Update a Payment Setup

Beta

Updates a Payment Setup.

Update the Payment Setup whenever there are significant changes in the data relevant to the customer's transaction. For example, when the customer makes a change that impacts the total payment amount.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string

The unique identifier of the Payment Setup to update.

Request Body schema: application/json
required
processing_channel_id
required
string^(pc)_(\w{26})$

The processing channel to use for the payment.

amount
required
number

The payment amount, in the minor currency unit.

currency
required
string

The currency of the payment, as a three-letter ISO currency code.

payment_type
string
Default: "Regular"

The type of payment.

You must provide this field for card payments in which the cardholder is not present. For example, if the transaction is a recurring payment, or a mail order/telephone order (MOTO) payment.

Enum: "Regular" "Recurring" "MOTO" "Installment" "PayLater" "Unscheduled"
reference
string <= 80 characters

A reference you can use to identify the payment. For example, an order number.

description
string <= 100 characters

A description of the payment.

object

The payment methods that are enabled on your account and available for use.

object

Settings for the Payment Setup.

object

The customer's details.

object

The customer's order details.

object (PaymentSetupBilling)

The billing details for the payment.

object

Industry-specific information.

Responses
200

Payment Setup updated.

400

The request is invalid. See the response body for details.

401

Authentication failed. Provide a valid API key or access token.

403

You do not have permission to update this Payment Setup.

422

One or more fields failed validation. See the response body for details.

put/payments/setups/{id}
Request samples
application/json
{
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount": 10000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "reference": "REF-0987-475",
  • "description": "Set of 3 t-shirts",
  • "payment_methods": {
    },
  • "settings": {},
  • "customer": {
    },
  • "order": {
    },
  • "billing": {
    },
  • "industry": {
    }
}
Response samples
application/json
{
  • "id": "string",
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount": 10000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "reference": "REF-0987-475",
  • "description": "Set of 3 t-shirts",
  • "payment_methods": {
    },
  • "available_payment_methods": [
    ],
  • "settings": {},
  • "customer": {
    },
  • "order": {
    },
  • "billing": {
    },
  • "industry": {
    }
}

Get a Payment Setup

Beta

Retrieves a Payment Setup by its unique identifier.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string

The unique identifier of the Payment Setup to retrieve.

Responses
200

Payment Setup details returned.

401

Authentication failed. Provide a valid API key.

403

You do not have permission to retrieve this Payment Setup.

get/payments/setups/{id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount": 10000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "reference": "REF-0987-475",
  • "description": "Set of 3 t-shirts",
  • "payment_methods": {
    },
  • "available_payment_methods": [
    ],
  • "settings": {},
  • "customer": {
    },
  • "order": {
    },
  • "billing": {
    },
  • "industry": {
    }
}
Confirm a Payment Setup
Beta


Confirm a Payment Setup to begin processing the payment request with your chosen payment method.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The unique identifier of the Payment Setup.


 
payment_method_name
required
string
The name of the payment method to process the payment with (For example, tabby, klarna, card).


 
Responses 
201
Payment processed successfully


400
The request is invalid. See the response body for details.


401
Authentication failed. Provide a valid API key or access token.


403
You do not have permission to update this Payment Setup.


422
One or more fields failed validation. See the response body for details.


post/payments/setups/{id}/confirm/{payment_method_name}
Request samples 
Response samples 
application/json
{
  • "id": "pay_mbabizu24mvu3mela5njyhpit4",
  • "action_id": "act_mbabizu24mvu3mela5njyhpit4",
  • "amount": 6540,
  • "currency": "USD",
  • "approved": true,
  • "status": "Authorized",
  • "auth_code": "770687",
  • "response_code": "10000",
  • "response_summary": "Approved",
  • "3ds": {
    },
  • "risk": {
    },
  • "source": {
    },
  • "customer": {
    },
  • "processed_on": "2019-09-10T10:11:12Z",
  • "reference": "ORD-5023-4E89",
  • "processing": {
    },
  • "eci": "06",
  • "scheme_id": "489341065491658",
  • "_links": {}
}
➔ Next to Payment Links