Save a card for future transactions

United States
Canada
Europe

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:

ObjectTypeDescription
sequencestringIndicates the sequence of the transaction for the same payment card.
Values:
- First
- Subsequent
is_scheduledbooleanIndicates if the transaction is scheduled or part of an installment.
Values:
- True - Transaction is scheduled.
- False - Transaction is part of an installment.
Installments are only available in the US.
initiatorstringIndicates if the transaction is scheduled or part of an installment.
Values:
- True - Transaction is scheduled.
- False - Transaction is part of an installment. Installments are only available in the US.
installment_infostringInstallment information for the transaction.
bill_pay_indicatorstringIndicates if the transaction is a recurring or installment payment.
Values:
- Installment
- Recurring - For Canadian merchants, the value must be "Recurring"
invoice_numberstringInvoice number of the installment or recurring transaction.
descriptionstring(Associated with the installment_info parameter) Description of the installment or recurring transaction.

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.