Skip to content
Payments / Store payment details / Payment instruments

Payment instruments

Last updated: April 29, 2022

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

Create a card 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. 

Using the /payments endpoint

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.

Tip

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

Endpoint

For the full API specification, see the API reference.

    post

    https://api.checkout.com/payments

    Request example

    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
    }

    Response example

    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": "JPMORGAN CHASE BANK NA",
      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
      }

      Using the /instruments endpoint

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

      Note

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

      Endpoints

      For the full API specification, see the API reference.

        post

        https://api.checkout.com/instruments

        Request example

        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": "Checkout.com",
        7
              "address_line2": "90 Tottenham Court Road",
        8
              "city": "London",
        9
              "state": "London",
        10
              "zip": "W1T 4TJ",
        11
              "country": "GB"
        12
            },
        13
            "phone": {
        14
              "country_code": "975",
        15
              "number": "174217187"
        16
            }
        17
          },
        18
          "customer": {
        19
            "email": "JohnTest@test.com",
        20
            "name": "John Test"
        21
          }
        22
        }

        Response examples

        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": "GOTHAM STATE BANK",
          13
            "issuer_country": "US",
          14
            "product_id": "F",
          15
            "product_type": "CLASSIC",
          16
            "customer": {
          17
              "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
          18
              "email": "JohnTest@test.com",
          19
              "name": "John Test"
          20
            }
          21
          }

          Get instrument details

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

          Endpoints

          For the full API specification, see the API reference.

            get

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

            Response example

            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 Test",
            8
              "scheme": "VISA",
            9
              "last4": "9996",
            10
              "bin": "454347",
            11
              "card_type": "Credit",
            12
              "card_category": "Consumer",
            13
              "issuer": "GOTHAM STATE BANK",
            14
              "issuer_country": "US",
            15
              "product_id": "F",
            16
              "product_type": "CLASSIC",
            17
              "account_holder": {
            18
                "billing_address": {
            19
                  "address_line1": "Checkout.com",
            20
                  "address_line2": "90 Tottenham Court Road",
            21
                  "city": "London",
            22
                  "state": "London",
            23
                  "zip": "W1T 4TJ",
            24
                  "country": "GB"
            25
                },
            26
                "phone": {
            27
                  "country_code": "975",
            28
                  "number": "174217187"
            29
                }
            30
              },
            31
              "customer": {
            32
                "id": "cus_gajmdgunwwlehbctuj6a3sifpm",
            33
                "email": "JohnTest@test.com",
            34
                "name": "John Test",
            35
                "default": true
            36
              }
            37
            }

            Update instrument details

            To update the details of a stored card 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.

            Endpoints

            For the full API specification, see the API reference.

              patch

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

              Request example

              1
              {
              2
                "expiry_month": 6,
              3
                "expiry_year": 2025,
              4
                "name": "John Test",
              5
                "account_holder": {
              6
                  "billing_address": {
              7
                    "address_line1": "Checkout.com",
              8
                    "address_line2": "90 Tottenham Court Road",
              9
                    "city": "London",
              10
                    "state": "London",
              11
                    "zip": "W1T 4TJ",
              12
                    "country": "GB"
              13
                  },
              14
                  "phone": {
              15
                    "country_code": "975",
              16
                    "number": "174217187"
              17
                  }
              18
                },
              19
                "customer": {
              20
                  "id": "cus_gajmdgunwwlehbctuj6a3sifpm",
              21
                  "default": true
              22
                }
              23
              }

              Response example

              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
              }

              Delete an instrument

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

              Endpoints

              For the full API specification, see the API reference.

                delete

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

                Response

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

                On this page

                Create a card payment instrument
                Get instrument details
                Update instrument details
                Delete an instrument