After you generate a card token](doc:ecommerce-generating-a-card-token), use the source token to save cards-on-file (COF). With card-on-file payments, customers authorize merchants to store their payment details and also to use those details to complete payments for future transactions.

🚧

IMPORTANT

Clover requires that all apps saving card-on-file get the customer's consent before updating a customer profile with card information.

Clover provides several sandbox test cards that can be used when building your app.

Save a card for a new customer

To save a card for a new customer, create a customer by sending a POST request to the /v1/customers endpoint.

📘

NOTE

When you save a card on file using /v1/customers, Clover sets the card source token as a multi-pay token for the customer.

In the following example, set the source token value and relevant information about the customer. Set the authorization: Bearer as your OAuth-generated access_token. See the API reference for more information about other values you can set.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/customers' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"email":"[email protected]","firstName":"John","lastName":"Doe",
  "source":"{token}","shipping":{"address":{"city":"Sunnyvale","country":"US",
  "line1":"415 N Mathilda Ave","postal_code":"94085","state":"CA"}}}'

📘

NOTE

Email address is a required field. This field helps customers to be notified that their card data has been saved to their profile.

In response, a unique id (customer ID) is generated for the created customer. You can use this customer id as the source value to submit payments with a saved customer card.

Save a card for an existing customer

To save a card for an existing customer, update the customer record by sending a PUT request to the /v1/customers/{customerId} endpoint using the source token value.

In the following example, set the customerId and source token values. Set the authorization: Bearer as your OAuth-generated access_token. See the API reference for more information about other values you can set.

curl --request PUT \
  --url 'https://scl-sandbox.dev.clover.com/v1/customers/{customerId}' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"source":"{token}"}'

Subsequent payments with saved cards

To make a payment and then subsequent payments with a saved customer card, you can use either the customer id or the multi-pay card token as the source value in your payment request.

Use customer ID

To construct a charge request, set the amount (in cents), currency, and source as the customer id.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/charges' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'idempotency-key {uuid4_key}' \
  --header 'content-type: application/json' \
  --data '{"amount":2300,
  "currency":"usd",
  "source":"{customer_id}"}'

📘

NOTE

If your use case requires you to save one card per customer, set the source as the customer id in any subsequent payments for that customer. If you are saving multiple cards per customer, use the multi-pay token for that customer in subsequent payments.

Use a multi-pay card token

When you save a card on file using /v1/customers, Clover sets the card source token as a multi-pay token for the customer. If you set the source value as this multi-pay token for the customer, you must also include the required stored_credentials values in the payment request:

Multi-pay card token example

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/charges' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'idempotency-key {uuid4_key}' \
  --header 'content-type: application/json' \
  --data '{"amount":1800,
  "currency":"usd",
  "source":"{multi_pay_token}",
  "stored_credentials":{
  "sequence": "SUBSEQUENT",
  "is_scheduled": false,
  "initiator": "CARDHOLDER"}}'

See the API reference for more information about other POST /v1/charges values you can set.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/orders/{orderId}/pay' \
  --header 'accept: application/json'
  --header 'authorization: Bearer {access_token}'
  --header 'content-type: application/json'
  --data '{"source":"{multi_pay_token}",
  "email":"[email protected]e.com",
  "stored_credentials":{
  "sequence": "SUBSEQUENT",
  "is_scheduled": false,
  "initiator": "CARDHOLDER"}}'

See the API reference for more information about other POST /v1/orders/{orderId}/pay values you can set.