Customers

Last updated: April 29, 2022

Store a customer's details in a customer object to reuse in future payments. You can associate multiple payment instruments with the customer, and set a default payment instrument, which will be used when you use the customer ID as the source in a payment request.

You can store your customer's details and create a customer object in two ways: as part of the payment request, or separately using the /customers endpoint.

When you request a payment for a new customer, include the customer's email in the request (in the customer.email parameter) to create a new customer object in the Vault. The response will include a customer object containing the id (prefixed with cus_) of the newly stored customer.

You can use the customer.name parameter in the request to set a name for the new customer.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5  },
6  "amount": 6500,
7  "currency": "USD",
8  "customer": {
9    "email": "[email protected]",
10    "name": "John Smith"
11  }
12}

If the request was successful, you'll receive a 201 Success response. You'll find the ID (prefixed with cus_) of the newly created customer in the customer object, and the ID (prefixed with src_) of the newly created payment instrument in the source object (for example, the stored details of the card used in the payment).

This payment instrument will be set as the default for the new customer, so when you use the customer ID as the source in a future payment request, the payment will be made using that instrument.


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    "email": "[email protected]",
37    "name": "John Smith"
38  },
39  "processed_on": "2024-01-25T11:03:36Z",
40  "reference": "ORD-5023-4E89",
41  "_links": {
42    "self": {
43      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
44    },
45    "actions": {
46      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
47    },
48    "capture": {
49      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
50    },
51    "void": {
52      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
53    }
54  }
55}


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

Alternatively, you can create a customer object by passing the customer's details into the /customers endpoint.

For the full API specification, see the API reference.

post

https://api.checkout.com/customers


1{
2  "email": "[email protected]",
3  "name": "John Smith",
4  "phone": {
5    "country_code": "+1",
6    "number": "5551234567"
7  },
8  "metadata": {
9    "coupon_code": "NY2024",
10    "partner_id": 123989
11  }
12}

If successful, you'll receive a 201 success response containing the ID (prefixed with cus_) of the newly created customer.

Information

Each customer must have a unique email address – you cannot have multiple customers with the same one. If you provide an email in the request that belongs to an existing customer, you will receive a 422 response with the error code customer_email_already_exists.


1{
2  "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
3}


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

To retrieve the details of a particular customer, and the payment instruments associated with them, pass the customer's id or email into the following endpoint.

For the full API specification, see the API reference.

get

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

Note

You can pass either the id or the email in the path.

Field name Description

Field name	Description
`id` string required if `email` is not provided	The customer's identifier.
`email` string required if `id` is not provided	The customer's email address.

id

string

required

if email is not provided

The customer's identifier.

email

string

required

if id is not provided

The customer's email address.

If successful, you'll receive a 200 success response containing the customer's details and their associated payment instruments.


1{
2  "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
3  "email": "[email protected]",
4  "default": "src_imu3wifxfvlebpqqq5usjrze6y",
5  "name": "John Smith",
6  "phone": {
7    "country_code": "+1",
8    "number": "5551234567"
9  },
10  "metadata": {
11    "coupon_code": "NY2024",
12    "partner_id": 123989
13  },
14  "instruments": [
15    {
16      "id": "src_lmyvsjadlxxu7kqlgevt6ebkra",
17      "type": "card",
18      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
19      "expiry_month": 6,
20      "expiry_year": 2025,
21      "name": "John Smith",
22      "scheme": "VISA",
23      "last4": "9996",
24      "bin": "454347",
25      "card_type": "CREDIT",
26      "card_category": "CONSUMER",
27      "issuer": "Test Bank",
28      "issuer_country": "US",
29      "product_id": "F",
30      "product_type": "CLASSIC",
31      "account_holder": {
32        "billing_address": {
33          "address_line1": "123 Anywhere St.",
34          "address_line2": "Apt. 456",
35          "city": "Anytown",
36          "state": "AL",
37          "zip": "123456",
38          "country": "US"
39        },
40        "phone": {
41          "country_code": "+1",
42          "number": "5551234567"
43        }
44      }
45    }
46  ]
47}

If you want to update the details of an existing customer, pass the customer's id and any new information into this endpoint.

For the full API specification, see the API reference.

patch

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

Information

If you include metadata in your request, it will replace any existing metadata stored for customer.

If successful, you'll receive a 204 success response – the customer's details have been updated.

If you want to delete a customer and all of the payment instruments associated with them, pass the customer id into the following endpoint.

For the full API specification, see the API reference.

delete

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

If successful, you'll receive a 204 success response – the customer, and all of their linked payment instruments, have been deleted.

Customers

Create a customer

Using the /payments endpoint

Endpoints

Request example

Response example

Using the /customers endpoint

Endpoints

Request example

Response example

Information

Get customer details

Endpoints

Path parameters

Note

Response example

Update customer details

Endpoints

Information

Response

Delete a customer

Endpoints

Response