Skip to content

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.

Create a customer

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.

Using the /payments 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.

Endpoints

post

https://api.checkout.com/payments

Request example

1
{
2
  "source": {
3
    "type": "token",
4
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5
  },
6
  "amount": 6500,
7
  "currency": "USD",
8
  "customer": {
9
    "email": "john.smith@example.com",
10
    "name": "John Smith"
11
  }
12
}

Response example

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 (ie, the stored details of the card used in the payment) in the source object.

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": "john.smith@example.com",
37
    "name": "John Smith"
38
  },
39
  "processed_on": "2019-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
}

Using the /customers endpoint

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.

Endpoints

post

https://api.checkout.com/customers

Request example

1
{
2
  "email": "john.smith@example.com",
3
  "name": "John Smith",
4
  "phone": {
5
    "country_code": "+1",
6
    "number": "5551234567"
7
  },
8
  "metadata": {
9
    "coupon_code": "NY2018",
10
    "partner_id": 123989
11
  }
12
}

Response example

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
}

Get customer details

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.

Endpoints

get

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

Path parameters

Note

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

Field nameDescription

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.

Response example

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": "john.smith@example.com",
4
  "default": "src_imu3wifxfvlebpqqq5usjrze6y",
5
  "name": "John Smith",
6
  "phone": {
7
    "country_code": "+1",
8
    "number": "5551234567"
9
  },
10
  "metadata": {
11
    "coupon_code": "NY2018",
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
}

Update customer details

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.

Endpoints

patch

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

Metadata

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

Response

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

Delete a customer

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.

Endpoints

delete

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

Response

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

On this page

Create a customer
Get customer details
Update customer details
Delete a customer