Stored payment instrument for Payment Setup API

Last updated: October 21, 2026

A stored payment instrument is an existing, previously saved payment source, such as a saved card or bank account, that Checkout.com already holds on file for your customer. Use the instrument payment method to submit the ID of a stored payment instrument, instead of collecting the customer's payment details again.

To accept payments using a stored payment instrument, you must:

Create a payment setup.
Update the payment setup with the stored instrument's ID.
Verify payment authorization.
Confirm the payment.

Call the Create a payment setup endpoint.

Information

The Payment Setup API supports idempotency. You can safely retry API requests without the risk of duplicate requests.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "USD",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Stored payment instrument payment",
7  "payment_type": "regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  }
12}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – The payment currency


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "USD",
6  "payment_type": "regular",
7  "reference": "ORDER_01234",
8  "description": "Stored payment instrument payment",
9  "payment_methods": {
10    "instrument": {
11      "id": "src_wmlfc3zttb4uzmk6snpwb43jbi",
12      "status": "action_required",
13      "flags": [],
14      "action": {
15        "type": "set_instrument"
16      }
17    }
18  },
19  "available_payment_methods": [
20    "instrument"
21  ],
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

For a stored payment instrument, payment_methods contains the following fields:

status – The status of the payment method.
flags – An array of error codes or indicators that highlight missing or invalid information.
action – Present when status is action_required. action.type is set to set_instrument, which indicates you must update the payment setup with the ID of a stored payment instrument before you can proceed.

When the customer selects a stored payment instrument as the payment method, call the Update a payment setup endpoint and provide the ID of the stored instrument.

Additionally, provide the following fields:

Field Description

Field	Description
`payment_methods.instrument.id` string	The ID of the stored payment instrument to use for this payment setup. Required

payment_methods.instrument.id

string

The ID of the stored payment instrument to use for this payment setup.
Required

When you submit the instrument id, we validate it and check that it supports the requested payment_type:

Pending – If the instrument requires asynchronous validation, we add instrument_pending to payment_methods.instrument.flags and set status to pending. This currently applies only to Bacs instruments, which take about five days to validate, so do not poll the payment setup. For the first Bacs payment, use the Bacs payment method instead of a stored instrument. If you do receive a pending status, wait for the Payment method ready webhook.
Invalid – If the instrument id doesn't correspond to a valid, existing instrument, we add instrument_invalid to payment_methods.instrument.flags and set status to invalid. Ask your customer for a different payment method.
Payment type mismatch – If the stored instrument doesn't support the requested payment_type, for example, a recurring-only instrument used for a regular payment, we add payment_type_mismatch to payment_methods.instrument.flags and set status to invalid. Ask your customer for a different payment method, or update the payment setup with a supported payment_type.


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "USD",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Stored payment instrument payment",
7  "payment_type": "regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  },
12  "payment_methods": {
13    "instrument": {
14      "id": "src_wmlfc3zttb4uzmk6snpwb43jbi",
15      "account_holder": {
16        "type": "individual",
17        "first_name": "Toby",
18        "last_name": "Arden"
19      },
20      "preferred_scheme": "visa"
21    }
22  }
23}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "USD",
6  "payment_type": "regular",
7  "reference": "ORDER_01234",
8  "description": "Stored payment instrument payment",
9  "payment_methods": {
10    "instrument": {
11      "type": "card",
12      "status": "ready",
13      "flags": []
14    }
15  },
16  "available_payment_methods": [
17    "instrument"
18  ],
19  "settings": {
20    "success_url": "https://example.com/payments/success",
21    "failure_url": "https://example.com/payments/failure"
22  }
23}

The response returns a ready status when the instrument has been successfully validated. The payment is ready to confirm.

The response also returns payment_methods.instrument.type, the underlying instrument's actual type, for example card or bacs.

We validate stored payment instruments synchronously, so the update response already contains the final status and you do not need to poll before you confirm the payment. To retrieve the current state of a payment setup, for example after your customer reloads the page, call the Get a payment setup endpoint, setting the id of the payment setup as the id path parameter.

get

https://{prefix}.api.checkout.com/payments/setups/{id}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "USD",
6  "payment_type": "regular",
7  "reference": "ORDER_01234",
8  "description": "Stored payment instrument payment",
9  "payment_methods": {
10    "instrument": {
11      "id": "src_wmlfc3zttb4uzmk6snpwb43jbi",
12      "type": "card",
13      "status": "ready",
14      "flags": []
15    }
16  },
17  "available_payment_methods": [
18    "instrument"
19  ],
20  "settings": {
21    "success_url": "https://example.com/payments/success",
22    "failure_url": "https://example.com/payments/failure"
23  }
24}

When the payment method status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
instrument as the payment method name.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/instrument

Stored payment instrument for Payment Setup API

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Response example

Verify payment authorization

Response example

Confirm the payment