Save a card for future transactions
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 cardsource
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 customerid
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:
Object | Type | Description |
---|---|---|
sequence | string | Indicates the sequence of the transaction for the same payment card. Values: - First - Subsequent |
is_scheduled | boolean | Indicates 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. |
initiator | string | Indicates 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_info | string | Installment information for the transaction. |
bill_pay_indicator | string | Indicates if the transaction is a recurring or installment payment. Values: - Installment - Recurring - For Canadian merchants, the value must be "Recurring" |
invoice_number | string | Invoice number of the installment or recurring transaction. |
description | string | (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.
Updated 4 days ago