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

    Copied!

    Request example

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

    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
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      {
      "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"
      }
      }
      }

      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

        Copied!

        Request example

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        {
        "email": "JohnTest@test.com",
        "name": "John Test",
        "phone": {
        "country_code": "+1",
        "number": "4155552671"
        },
        "metadata": {
        "coupon_code": "NY2018",
        "partner_id": 123989
        }
        }

        Response example

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

        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
          3
          {
          "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44"
          }

          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}

            Copied!

            Path parameters

            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
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13
            14
            15
            16
            17
            18
            19
            20
            21
            22
            23
            24
            25
            26
            27
            28
            29
            30
            31
            32
            33
            34
            35
            36
            37
            38
            39
            40
            41
            42
            43
            44
            45
            46
            47
            {
            "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"
            }
            }
            }
            ]
            }

            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}

              Copied!

              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}

                Copied!

                Response

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