Payment instruments

Last updated: October 21, 2026

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

You can also store your own metadata with a payment instrument.

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:

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

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://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
42    },
43    "actions": {
44      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
45    },
46    "capture": {
47      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
48    },
49    "void": {
50      "href": "https://{prefix}.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.

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/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": "john.smith@example.com",
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": "john.smith@example.com",
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.

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/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": "john.smith@example.com"
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": "jane.smith@example.com",
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": "jane.smith@example.com",
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.

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.

get

https://{prefix}.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": "jane.smith@example.com",
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": "john.smith@example.com"
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": "jane.smith@example.com",
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.

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.

patch

https://{prefix}.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": "john.smith@example.com"
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}

You can attach your own metadata object to a card or bank account payment instrument. For example, to store a customer's document number or a partner reference with their card.

You can then reference the metadata in Forward API requests, so the value is added to every request you forward to a third party, without your systems having to look it up.

Metadata is stored encrypted, and is returned exactly as you provided it when you get instrument details. It's also returned for each instrument in the instruments array when you call the Get customer details endpoint.

The stored metadata is kept when you update other instrument details, and when Account Updater refreshes the card details.

Note

Metadata is for your own references. Do not store card details, credentials, or personal data you do not have consent to store.

The metadata object must be a flat JSON object that meets the following requirements:

A maximum of 20 key-value pairs
Keys between 1 and 100 characters long
Values up to 100 characters long
Keys and values are strings. Nested objects, arrays, numbers, Boolean values, and null values are not supported.

Keys are case-sensitive. For example, documentNumber and documentnumber are different keys.

If the metadata object does not meet these requirements, you receive a 422 response with one or more of the following error codes:

Error code	Reason
`too_many_metadata_items`	The object contains more than 20 key-value pairs.
`metadata_key_invalid`	A key is an empty string.
`metadata_key_too_long`	A key is longer than 100 characters.
`metadata_value_too_long`	A value is longer than 100 characters.
`metadata_value_invalid`	A value is `null`.
`metadata_only_supported_for_token_type_card`	You provided `metadata` when creating a token with a `type` other than `card`.

If the request fails more than one requirement, you receive an error code for each one.

These error codes are also listed in Error codes.

Provide the metadata object in your Create an instrument request. You can provide metadata for card, bank_account, and token instrument types.

If you provide an empty object ({}), no metadata is stored. For token instruments, an empty object is treated as not provided, so the token's metadata is stored instead.


1{
2  "type": "token",
3  "token": "tok_ubfj2q76miwundwlk72vxt2i7q",
4  "metadata": {
5    "documentNumber": "12345678900"
6  }
7}


1{
2  "id": "src_wmlfc3zyhqzehihu7giusaaawu",
3  "type": "card",
4  "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
5  "expiry_month": 6,
6  "expiry_year": 2030,
7  "scheme": "VISA",
8  "last4": "4242",
9  "bin": "424242",
10  "metadata": {
11    "documentNumber": "12345678900"
12  }
13}

Information

If the request matches a payment instrument you've already stored, for example the same card for the same customer, the response returns the existing instrument's metadata. The metadata in your request is not stored. To change it, update the instrument metadata.

If you created a card token with metadata using the Request a token endpoint, the metadata is stored with the token for the token's 15-minute lifetime. When you convert the token into a payment instrument:

If you provide a non-empty metadata object in the Create an instrument request, the request's metadata is stored in full and the token's metadata is discarded.
If you do not provide metadata, or you provide an empty object, the token's metadata is stored with the instrument.

The two objects are never merged.

You can only provide metadata for tokens with the card type.

To change the metadata, call the Update an instrument endpoint and provide the full metadata object. You can send a request that only contains metadata, without changing any card or bank account details.

The metadata object you provide replaces the stored object in full. Individual keys are not merged, so to change one key, provide the full object with that key updated.

To remove all metadata, provide an empty object ({}).
To keep the stored metadata, do not include metadata in the request, or set it to null.


1{
2  "metadata": {
3    "documentNumber": "99900011122"
4  }
5}

If successful, you receive a 200 response.

If two update requests for the same instrument are processed at the same time, one succeeds and the other returns a 409 response. Get the latest instrument details, reapply your intended change to the full metadata object, then send the update again.

Note

The instrument's top-level metadata object is separate from the customer.metadata object, which belongs to the linked customer.

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

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.

delete

https://{prefix}.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

Create a card payment instrument

Information

Using the Payments API

Information

Request example

Response example

Using the Instruments API

Note

Information

Request example

Response example

Create a bank account payment instrument

Get bank account field formatting

Create the instrument

Information

Request example

Response example

Testing

Get instrument details

Information

Response example

Update instrument details

Information

Request example

Response example

Store metadata with an instrument

Note

Metadata requirements

Add metadata when you create an instrument

Request example

Response example

Information

Create an instrument from a token with metadata

Update instrument metadata

Request example

Note

Delete an instrument

Information

Response

View stored payment instruments