Payment instruments

Last updated: November 19, 2025

You can store a customer's card or bank account details as a payment instrument to reuse in future payments or payouts.

You can store card details as a payment instrument using the following APIs:

Payments API – To make a payment with a card token or full card details, or verify a card
Instruments API – To convert a card token into a payment instrument

Information

We recommend using the Payments API if you process payments with Checkout.com, because we check that the card is valid before storing it.

With both APIs, you can create an instrument for a new customer, or an existing one.

If you provide:

A new email in the customer object – We create a new customer and link them to the instrument.
An existing customer ID or email – We link the instrument to the existing customer.

Call the Request a payment or payout endpoint:

post

https://api.checkout.com/payments

The following example includes the ID of an existing customer, who is then linked to the payment instrument.


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5  },
6  "amount": 6500,
7  "currency": "USD",
8  "customer": {
9    "customer.id": "cus_udst2tfldj6upmye2reztkmm4i"
10  }
11}

If successful, you receive a 201 response that includes the payment instrument ID in the source.id field, prefixed with src_. You can use this in future payment requests.

It also includes the linked customer's ID in the customer.id field, prefixed with cus_.


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 6500,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "eci": "05",
10  "scheme_id": "638284745624527",
11  "response_code": "10000",
12  "response_summary": "Approved",
13  "risk": {
14    "flagged": false
15  },
16  "source": {
17    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
18    "type": "card",
19    "expiry_month": 9,
20    "expiry_year": 2022,
21    "scheme": "Visa",
22    "last4": "4242",
23    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
24    "bin": "424242",
25    "card_type": "CREDIT",
26    "card_category": "CONSUMER",
27    "issuer": "Test Bank",
28    "issuer_country": "US",
29    "product_id": "A",
30    "product_type": "Visa Traditional",
31    "avs_check": "S",
32    "cvv_check": ""
33  },
34  "customer": {
35    "id": "cus_udst2tfldj6upmye2reztkmm4i"
36  },
37  "processed_on": "2024-01-25T11:03:36Z",
38  "reference": "ORD-5023-4E89",
39  "_links": {
40    "self": {
41      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
42    },
43    "actions": {
44      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
45    },
46    "capture": {
47      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
48    },
49    "void": {
50      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
51    }
52  }
53}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

Call the Create an instrument endpoint:

Note

This endpoint does not check that the card is valid before storing it.

post

https://api.checkout.com/instruments

This example provides a new customer email and name. This creates a new customer and the payment instrument automatically becomes their default instrument.


1{
2  "type": "token",
3  "token": "tok_asoto22g2fsu7prwomy12sgfsa",
4  "account_holder": {
5    "billing_address": {
6      "address_line1": "123 Anywhere St.",
7      "address_line2": "Apt. 456",
8      "city": "Anytown",
9      "state": "AL",
10      "zip": "123456",
11      "country": "US"
12    },
13    "phone": {
14      "country_code": "+1",
15      "number": "5551234567"
16    }
17  },
18  "customer": {
19    "email": "[email protected]",
20    "name": "John Smith"
21  }
22}

If successful, you receive a 201 response that includes the instrument id, prefixed with src_. You can use this in future payment requests.

It also returns the details of the linked customer.


1{
2  "id": "src_wmlfc3zyhqzehihu7giusaaawu",
3  "type": "card",
4  "fingerprint": "string",
5  "expiry_month": 6,
6  "expiry_year": 2025,
7  "scheme": "VISA",
8  "last4": "9996",
9  "bin": "454347",
10  "card_type": "CREDIT",
11  "card_category": "CONSUMER",
12  "issuer": "Test Bank",
13  "issuer_country": "US",
14  "product_id": "F",
15  "product_type": "CLASSIC",
16  "customer": {
17    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
18    "email": "[email protected]",
19    "name": "John Smith"
20  }
21}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

Before creating a bank account payment instrument, call the Get bank account field formatting endpoint to check the required fields for the account's country and currency.

Alternatively, see Payout formatting.

Call the Create an instrument endpoint to convert the bank account details into a bank account payment instrument.

post

https://api.checkout.com/instruments


1{
2  "type": "bank_account",
3  "account_type": "savings",
4  "account_number": "13654567455",
5  "bank_code": "123-456",
6  "branch_code": "6443",
7  "iban": "HU93116000060000000012345676",
8  "bban": "3704 0044 0532 0130 00",
9  "swift_bic": "37040044",
10  "currency": "GBP",
11  "country": "GB",
12  "account_holder": {
13    "type": "individual",
14    "first_name": "John",
15    "last_name": "Smith",
16    "company_name": "Acme Corporation",
17    "tax_id": "123456",
18    "date_of_birth": "1986-01-01",
19    "country_of_birth": "GB",
20    "residential_status": "resident",
21    "billing_address": {
22      "address_line1": "123 High St.",
23      "address_line2": "Flat 456",
24      "city": "London",
25      "zip": "SW1A 1AA",
26      "country": "GB"
27    },
28    "phone": {
29      "country_code": "+44",
30      "number": "1234 567890"
31    },
32    "identification": {
33      "type": "passport",
34      "number": "09876",
35      "issuing_country": "US"
36    },
37    "email": "[email protected]"
38  },
39  "bank": {
40    "name": "Test Bank",
41    "branch": "Main branch",
42    "address": {
43      "address_line1": "Example Place",
44      "address_line2": "Example Square",
45      "city": "London",
46      "zip": "EC2M 4XY",
47      "country": "GB"
48    }
49  },
50  "customer": {
51    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
52    "email": "[email protected]",
53    "name": "Jane Smith"
54  }
55}

If successful, the response returns the bank account payment instrument id, prefixed with src_. You can use this for Bank Payout requests.

The response also returns a fingerprint, which is a unique token that identifies the instrument across all customers.


1{
2  "type": "bank_account",
3  "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
4  "customer": {
5    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
6    "email": "[email protected]",
7    "name": "Jane Smith"
8  },
9  "id": "src_wmlfc3zyhqzehihu7giusaaawu"
10}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

To test different payment instrument scenarios, see Testing.

To retrieve a specific payment instrument's details, call the Get instrument details endpoint, and provide the instrument ID as the {id} path parameter.

get

https://api.checkout.com/instruments/{id}

If successful, you receive a 200 response containing the instrument's details.


1{
2  "id": "src_lmyvsjadlxxu7kqlgevt6ebkra",
3  "type": "card",
4  "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
5  "expiry_month": 6,
6  "expiry_year": 2025,
7  "name": "John Smith",
8  "scheme": "VISA",
9  "last4": "9996",
10  "bin": "454347",
11  "card_type": "CREDIT",
12  "card_category": "CONSUMER",
13  "issuer": "Test Bank",
14  "issuer_country": "US",
15  "product_id": "F",
16  "product_type": "CLASSIC",
17  "account_holder": {
18    "billing_address": {
19      "address_line1": "123 High St.",
20      "address_line2": "Flat 456",
21      "city": "London",
22      "zip": "SW1A 1AA",
23      "country": "GB"
24    },
25    "phone": {
26      "country_code": "+44",
27      "number": "1234 567890"
28    }
29  },
30  "customer": {
31    "id": "cus_gajmdgunwwlehbctuj6a3sifpm",
32    "email": "[email protected]",
33    "name": "Jane Smith",
34    "default": true
35  }
36}


1{
2  "type": "bank_account",
3  "id": "src_wmlfc3zyhqzehihu7giusaaawu",
4  "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
5  "account_type": "savings",
6  "account_number": "13654567455",
7  "bank_code": "123-456",
8  "branch_code": "6443",
9  "iban": "HU93116000060000000012345676",
10  "bban": "3704 0044 0532 0130 00",
11  "swift_bic": "37040044",
12  "currency": "GBP",
13  "country": "GB",
14  "account_holder": {
15    "type": "individual",
16    "first_name": "John",
17    "last_name": "Smith",
18    "company_name": "Acme Corporation",
19    "tax_id": "123456",
20    "date_of_birth": "1986-01-01",
21    "country_of_birth": "GB",
22    "residential_status": "resident",
23    "billing_address": {
24      "address_line1": "123 High St.",
25      "address_line2": "Flat 456",
26      "city": "London",
27      "zip": "SW1A 1AA",
28      "country": "GB"
29    },
30    "phone": {
31      "country_code": "+44",
32      "number": "1234 567890"
33    },
34    "identification": {
35      "type": "passport",
36      "number": "09876",
37      "issuing_country": "US"
38    },
39    "email": "[email protected]"
40  },
41  "bank": {
42    "name": "Test Bank",
43    "branch": "Main branch",
44    "address": {
45      "address_line1": "Example Place",
46      "address_line2": "Example Square",
47      "city": "London",
48      "zip": "EC2M 4XY",
49      "country": "GB"
50    }
51  },
52  "customer": {
53    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
54    "email": "[email protected]",
55    "name": "Jane Smith",
56    "default": true
57  }
58}

To update the details of a payment instrument, call the Update an instrument endpoint, and provide the instrument ID as the {id} path parameter.

For example, you can update the stored card's expiry month and year, or make the instrument the linked customer's default instrument.

patch

https://api.checkout.com/instruments/{id}


1{
2  "expiry_month": 6,
3  "expiry_year": 2025,
4  "name": "John Smith",
5  "account_holder": {
6    "billing_address": {
7      "address_line1": "123 High St.",
8      "address_line2": "Flat 456",
9      "city": "London",
10      "zip": "SW1A 1AA",
11      "country": "GB"
12    },
13    "phone": {
14      "country_code": "+44",
15      "number": "1234 567890"
16    }
17  },
18  "customer": {
19    "id": "cus_gajmdgunwwlehbctuj6a3sifpm",
20    "default": true
21  }
22}


1{
2  "type": "bank_account",
3  "account_type": "savings",
4  "account_number": "13654567455",
5  "bank_code": "123-456",
6  "branch_code": "6443",
7  "iban": "HU93116000060000000012345676",
8  "bban": "3704 0044 0532 0130 00",
9  "swift_bic": "37040044",
10  "currency": "GBP",
11  "country": "GB",
12  "account_holder": {
13    "type": "individual",
14    "first_name": "John",
15    "last_name": "Smith",
16    "company_name": "Acme Corporation",
17    "tax_id": "123456",
18    "date_of_birth": "1986-01-01",
19    "country_of_birth": "GB",
20    "residential_status": "resident",
21    "billing_address": {
22      "address_line1": "123 High St.",
23      "address_line2": "Flat 456",
24      "city": "London",
25      "zip": "SW1A 1AA",
26      "country": "GB"
27    },
28    "phone": {
29      "country_code": "+44",
30      "number": "1234 567890"
31    },
32    "identification": {
33      "type": "passport",
34      "number": "09876",
35      "issuing_country": "US"
36    },
37    "email": "[email protected]"
38  },
39  "bank": {
40    "name": "Test Bank",
41    "branch": "Main branch",
42    "address": {
43      "address_line1": "Example Place",
44      "address_line2": "Example Square",
45      "city": "London",
46      "zip": "EC2M 4XY",
47      "country": "GB"
48    }
49  },
50  "customer": {
51    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
52    "default": true
53  }
54}

If successful, you receive a 200 response that contains the updated instrument fingerprint. This is a token you can use to identify the card across all customers.


1{
2  "type": "card",
3  "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
4}


1{
2  "type": "bank_account",
3  "fingerprint": "smoua2sbuqhupeofwbe77n5nsm"
4}

To delete a payment instrument, call the Delete an instrument endpoint, and provide the instrument ID as the {id} path parameter.

delete

https://api.checkout.com/instruments/{id}

If successful, you receive a 204 response.

You can view your stored payment instruments in the Dashboard.

Sign in to the Dashboard.
Go to Vault > Payment instruments.

On this page, you can view:

The total number of stored payment instruments
A breakdown of the types of stored payment instruments – for example, cards and digital wallets

Select a payment instrument to view its details, including:

The payment instrument ID
The date the instrument was created
The date the instrument was last modified
The instrument details – for example, the linked customer's ID and the payment method type
The payment method details – for example:
- For card payment instruments – The card scheme and card type
- For bank-account payment instruments – The bank name and currency

Payment instruments

Create a card payment instrument

Information

Using the Payments API

Request example

Response example

Using the Instruments API

Note

Request example

Response example

Create a bank account payment instrument

Get bank account field formatting

Create the instrument

Request example

Response example

Testing

Get instrument details

Response example

Update instrument details

Request example

Response example

Delete an instrument

Response

View stored payment instruments