Payment instruments

Last updated: April 29, 2022

Store a customer's card or bank account as a payment instrument to reuse it in future payments or payouts.

Create a card payment instrument.
Create a bank account payment instrument.

You can store a card as a payment instrument in two ways: using the /payments endpoint, or using the /instruments endpoint.

In both cases, you can create a payment instrument for a new customer, or an existing one:

If you provide a new email in the customer object, a new customer will be created and linked with the new payment instrument.
If you supply an existing customer ID or email, the new payment instrument will be linked to that existing customer.

Make a payment (with a card token or full card details) or verify a card with the /payments endpoint, and the ID of the newly created payment instrument will be included in the response.

For the full API specification, see the API reference.

Information

We recommend this flow if you perform payments with us, because we will check the card is valid before storing it.

post

https://api.checkout.com/payments

Information

In this example, the ID of an existing customer has been supplied, so the payment instrument will be linked to this existing customer.


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 the request was successful, you will receive 201 success response. This will include a source.id (prefixed with src_) – this is the payment instrument ID. You can use this in future payment requests.

It will also include the customer.id (prefixed with cus_) – the ID of the customer to which the new payment instrument has been linked.


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": "2019-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}

Alternatively, you can convert a card token into a payment instrument using the /instruments endpoint.

For the full API specification, see the API reference.

Note

Using this flow will not check the card is valid before storing it.

post

https://api.checkout.com/instruments

Information

In this example, a new customer email and name is provided. This will create a new customer and the payment instrument will automatically become this customer's 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 the request was successful, you will receive a 201 success response. This will include the newly created payment instrument id (prefixed with src_), which you can now use in future payment requests.

It will also include the details of the customer to which the new instrument has been linked.


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, use the get bank account field formatting endpoint to check which fields are required for the country and currency of the account.

You can explore the required fields for each country we support in our formatting guide.

Convert bank account details into a bank account payment instrument using the /instruments endpoint.

For the full API specification, see the API reference.

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 will include the id (prefixed with src_) of the newly created bank account payment instrument, which you can now use in bank payout requests, and a fingerprint, which is a unique token that can identify this 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}

Information

Test different payment instrument scenarios using our testing guide.

To retrieve the details of a particular payment instrument, pass the instrument's id into the following endpoint.

For the full API specification, see the API reference.

get

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

If successful, you will receive a 200 success response containing all the details of the payment instrument.


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, use the following request. For example, you can update the expiry month and year of the stored card, or make it the default payment instrument of the customer associated with the card.

For the full API specification, see the API reference.

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 will receive a 200 success response containing the fingerprint of the updated card instrument – 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}

If you want to delete a payment instrument, pass the instrument's id in the following request.

For the full API specification, see the API reference.

delete

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

If the instrument was successfully deleted, you will receive a 204 success response.

Payment instruments

Create a card payment instrument

Using the /payments endpoint

Information

Endpoints

Request example

Information

Response example

Using the /instruments endpoint

Note

Endpoints

Request example

Information

Response example

Create a bank account payment instrument

Get bank account field formatting

Create the instrument

Endpoints

Request example

Response example

Information

Get instrument details

Endpoints

Response example

Update instrument details

Endpoints

Request example

Response example

Delete an instrument

Endpoints

Response