Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Payment instruments

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.

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

The request

Endpoint
https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments
Header parameters
HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json
Body parameters

The table below describes the request using a card token. You can also use full card details. For the full API specification, see the API reference.


Field nameDescription

source

OBJECT

REQUIRED

Details about the payment source.

source.type

STRING

REQUIRED

The type of payment source. Set this to token for a card token, or card if you're using full card details. (This example uses token.)

source.token

STRING

REQUIRED

The Checkout.com token.

amount

INTEGER

OPTIONAL

The payment amount in your chosen currency. Omit the amount or provide a value of 0 to perform a card verification.

The format depends on the currency. For more information, see calculating the value.

currency

STRING

REQUIRED

A three-letter ISO currency code representing the currency of the payment.

reference

STRING

OPTIONAL

An optional reference you can use to identify the payment later. For example, an order number.

customer

OBJECT

OPTIONAL

The customer's details.

customer.id

STRING

OPTIONAL

The identifier of an existing customer. Provide this (or an existing email) if you want to link the new payment instrument to an existing customer.

customer.email

STRING

OPTIONAL

The customer's email address. Provide an existing one (or an existing id) if you want to link the new payment instrument to an existing customer, or provide a new email if you want to create a new customer to which the payment instrument will belong.

customer.name

STRING

OPTIONAL

The customer's name. This will only set the name for new customers.

metadata

OBJECT

OPTIONAL

Allows you to store additional information about a transaction (e.g., a coupon code) with custom fields and up to five user-defined fields (udf1 to udf5), which can be used for reporting purposes.

udf1 is also used for some of our risk rules.

Request example

In this example, the ID of an existing customer has been supplied, so the payment instrument will be linked to this existing customer.


{
  "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
  },
  "amount": 6500,
  "currency": "USD"
  "customer": {
    "customer.id": "cus_udst2tfldj6upmye2reztkmm4i"
  }
}

The response

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.

Response example
{
  "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"
  },
  "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"
    }
  }
}
{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": [
    "payment_source_required"
  ]
}

Using the /instruments endpoint

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

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

The request

Endpoint
https://api.checkout.com/instruments
https://api.sandbox.checkout.com/instruments
Header parameters
HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json
Body parameters
Field nameDescription

type

STRING

REQUIRED

The instrument type. Set this to token.

token

STRING

REQUIRED

The Checkout.com token.

account_holder

OBJECT

OPTIONAL

The customer's billing address and phone number.

customer

OBJECT

OPTIONAL

The customer's details.

customer.id

STRING

OPTIONAL

The identifier of an existing customer. Provide this (or an existing email) if you want to link the new payment instrument to an existing customer.

customer.email

STRING

OPTIONAL

The customer's email address. Provide an existing one (or an existing id) if you want to link the new payment instrument to an existing customer, or provide a new email if you want to create a new customer to which the payment instrument will belong.

customer.name

STRING

OPTIONAL

The customer's name. This will only set the name for new customers.

customer.default

BOOLEAN

OPTIONAL

If true, the instrument will be made the default for the customer. If you're creating a new customer in this request, the instrument will automatically be the default.
Request example

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.


{
  "type": "token",
  "token": "tok_asoto22g2fsu7prwomy12sgfsa",
  "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"
    }
  },
  "customer": {
    "email": "JohnTest@test.com",
    "name": "John Test",
  }
}

The response

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.

Response example
{
  "id": "src_wmlfc3zyhqzehihu7giusaaawu",
  "type": "card",
  "fingerprint": "string",
  "expiry_month": 6,
  "expiry_year": 2025,
  "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",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "email": "JohnTest@test.com",
    "name": "John Test"
  }
}
{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": [
    "payment_source_required"
  ]
}

Get instrument details

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

The request

Endpoint

GEThttps://api.checkout.com/instruments/{id}
GEThttps://api.sandbox.checkout.com/instruments/{id}

Path parameters

Field nameDescription

id

STRING

REQUIRED

The instrument's identifier.

The response

If successful, you will receive a 200 success response containing all the details of the payment instrument.

Response example

{
  "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"
    }
  },
  "customer": {
    "id": "cus_gajmdgunwwlehbctuj6a3sifpm",
    "email": "JohnTest@test.com",
    "name": "John Test",
    "default": true
  }
}

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.

The request

Endpoint

PATCHhttps://api.checkout.com/instruments/{id}
PATCHhttps://api.sandbox.checkout.com/instruments/{id}

Path parameters

Field nameDescription

id

STRING

REQUIRED

The instrument's identifier.

Body parameters

Field nameDescription

expiry_month

INTEGER

OPTIONAL

The expiry month of the card.

expiry_year

INTEGER

OPTIONAL

The expiry year of the card.

name

INTEGER

OPTIONAL

The name of the customer.

account_holder

OBJECT

OPTIONAL

The billing address and phone number of the customer.

customer

OBJECT

OPTIONAL

The customer's details.

customer.id

STRING

OPTIONAL

The customer's identifier.

customer.default

STRING

OPTIONAL

If true, the instrument will be made the default for the customer. If false, no change will be made.

Request example

{
  "expiry_month": 6,
  "expiry_year": 2025,
  "name": "John Test",
  "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"
    }
  },
  "customer": {
    "id": "cus_gajmdgunwwlehbctuj6a3sifpm",
    "default": true
  }
}

The response

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.

Response example

{
  "type": "card",
  "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
}

Delete an instrument

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

The request

Endpoint

DELETEhttps://api.checkout.com/instruments/{id}
DELETEhttps://api.sandbox.checkout.com/instruments/{id}

Path parameters

Field nameDescription

id

STRING

REQUIRED

The instrument's identifier.

The response

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