Customers

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.

{
  "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
  },
  "amount": 6500,
  "currency": "USD",
  "customer": {
    "email": "john.test@example.com",
    "name": "John Test"
  }
}

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.

{
  "id": "pay_mbabizu24mvu3mela5njyhpit4",
  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
  "amount": 6500,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "auth_code": "770687",
  "eci": "05",
  "scheme_id": "638284745624527",
  "response_code": "10000",
  "response_summary": "Approved",
  "risk": {
    "flagged": false
  },
  "source": {
    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
    "type": "card",
    "expiry_month": 9,
    "expiry_year": 2022,
    "scheme": "Visa",
    "last4": "4242",
    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
    "bin": "424242",
    "card_type": "Credit",
    "card_category": "Consumer",
    "issuer": "JPMORGAN CHASE BANK NA",
    "issuer_country": "US",
    "product_id": "A",
    "product_type": "Visa Traditional",
    "avs_check": "S",
    "cvv_check": ""
  },
  "customer": {
    "id": "cus_udst2tfldj6upmye2reztkmm4i",
    "email": "john.test@example.com",
    "name": "John Test"
  },
  "processed_on": "2019-01-25T11:03:36Z",
  "reference": "ORD-5023-4E89",
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
    },
    "actions": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
    },
    "capture": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
    },
    "void": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
    }
  }
}

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.

{
  "email": "JohnTest@test.com",
  "name": "John Test",
  "phone": {
    "country_code": "+1",
    "number": "4155552671"
  },
  "metadata": {
    "coupon_code": "NY2018",
    "partner_id": 123989
  }
}

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

{
  "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
}

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.

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

{
  "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "email": "JohnTest@test.com",
  "default": "src_imu3wifxfvlebpqqq5usjrze6y",
  "name": "John Test",
  "phone": {
    "country_code": "+1",
    "number": "4155552671"
  },
  "metadata": {
    "coupon_code": "NY2018",
    "partner_id": 123989
  },
  "instruments": [
    {
      "id": "src_lmyvsjadlxxu7kqlgevt6ebkra",
      "type": "card",
      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",
      "expiry_month": 6,
      "expiry_year": 2025,
      "name": "John Test",
      "scheme": "VISA",
      "last4": "9996",
      "bin": "454347",
      "card_type": "Credit",
      "card_category": "Consumer",
      "issuer": "GOTHAM STATE BANK",
      "issuer_country": "US",
      "product_id": "F",
      "product_type": "CLASSIC",
      "account_holder": {
        "billing_address": {
          "address_line1": "Checkout.com",
          "address_line2": "90 Tottenham Court Road",
          "city": "London",
          "state": "London",
          "zip": "W1T 4TJ",
          "country": "GB"
        },
        "phone": {
          "country_code": "975",
          "number": "174217187"
        }
      }
    }
  ]
}

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.

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.

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