Create and use a card token
The API provides the /v1/card/tokens
endpoint to capture an encrypted card token and store or vault it for later use. This allows merchants to process recurring payments without the cardholder being present or to complete in-person transactions quickly for returning customers. Card tokens are one-way encrypted and can be stored on systems outside of PCI DSS scope.
NOTE
Tokenization through REST Pay Display API is not supported in Europe.
NOTE
Multipay card tokens created with this endpoint can also be used for card-not-present transactions using the Ecommerce API. See REST Pay and Ecommerce Interoperability for more information.
Prerequisites
- POS is connected to the device using a network or cloud connection.
- Clover device is in an idle state, that is, no payment is being taken.
- The merchant account is configured for multipay tokens. To confirm get the merchant's payment gateway information and verify that
supportsMultiPayToken
istrue
.
Vault a card
- To vault a card on the Clover device, do one of the following:
- To get an Ecommerce charge token, construct a request with the required data—the
tokenType
:
{
"tokenType": "ECOMM_COMPAT"
}
- When Ecommerce-compatible token is not needed, construct the request with an empty body.
- Send a POST request to the
/v1/card/tokens
endpoint. - Required. Include the required headers for your request.
The customer is asked to present their card. After the tokenization process is complete, a success message appears.
- See Display the welcome screen for instructions to display the default idle screen, or take other appropriate action.
NOTE
The returned token must have a
clv_
prefix to use with the Ecommerce API. If the token you receive is not prefixed, verify that your request specifies thetokenType
asECOMM_COMPAT
.
Take payments with vaulted cards
Take a payment with an Ecommerce card token
After you have a card token stored for a customer, you can make charges against the card with card-not-present.
- Construct a request for the charge with the order
amount
andcurrency
, and set thesource
value as the token.
- Include a receipt type and a
description
in the request. - With an Ecommerce charge, the customer cannot receive a physical receipt, so set their email address as the value of
receipt_email
. The following is an example of an Ecomm charge. Note the token (source
) has aclv_
prefix and the receipt is emailed to the customer.
{
"amount": 3000,
"currency": "usd",
"receipt_email": "[email protected]",
"description": "Message text",
"source": "{clv_TokenValue}",
"stored_credentials": {"sequence": "SUBSEQUENT", "is_scheduled": {SCHEDULED VALUE}, "initiator": "{MERCHANT or CUSTOMER}"}
}
- Send a POST request to the
{ecommBaseUrl}/v1/charges
endpoint.
The customer's card is charged for the specified amount. After the payment is complete, a success message appears.
{
"id": "YHT8X021TT270",
"amount": 3000,
"amount_refunded": 0,
"currency": "usd",
"created": 1617207089466,
"description": "Message text",
"captured": true,
"ref_num": "1167554668",
"auth_code": "851141",
"outcome": {
"network_status": "approved_by_network",
"type": "authorized"
},
"paid": true,
"status": "succeeded",
"source": {
"id": "clv_1TSTSQVqNDvM3t5SPBuGYT45",
"brand": "DISCOVER",
"exp_month": "12",
"exp_year": "2025",
"first6": "601136",
"last4": "6668"
}
}
Take a payment with a Clover legacy card token
After you have a card token stored for a customer, you can make charges against the card with card-not-present.
- Construct a request for the payment wit:
- The order
amount
. - An
externalPaymentId
. - A
vaultedCard
object with the required card information. - A
description
in the request.
{
"amount": 3000,
"description": "Message text",
"externalPaymentId": "{externalPaymentId}",
"vaultedCard": {
"expirationDate": "1221",
"token": "{tokenValue}",
"cardholderName": "Test Cardholder",
"first6": "601136",
"last4": "6668"
}
}
- Send a POST request to the
{baseUrl}/v1/payments
endpoint.
The customer's card is charged for the specified amount. After the payment is complete, a success message appears.
Updated 2 months ago