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 is true.

Vault a card

1. 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.

2. Send a POST request to the /v1/card/tokens endpoint.
3. 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.

4. 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 the tokenType as ECOMM_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.

1. Construct a request for the charge with the order amount and currency, and set the source 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 a clv_ 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}"}
}

2. 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.

1. 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"
  }
}

2. 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.