Check and use gift card balance

United States

Overview

A gift card is a prepaid payment card used for purchases at participating restaurants, stores, or online retailers, available in various denominations. Depending on the issuer’s terms, you can redeem these cards for services, merchandise, or cash.

Clover native gift cards managed through the Fiserv payment gateway, are integrated into the Clover point of sale (POS) system for seamless transactions. Physical gift cards have a 4-8 digit security card value (SCV), while virtual gift cards use a promo code.

Balance inquiry returns the current balance on an active gift card. On an active gift card, you can:

  • Inquire current balance and set a multi-lock on a specific balance amount for a specific period. One or more locks can be active on a gift card at any given time.
  • Request unlock, and redeem a multi-locked amount.
  • Request cashout for the gift card balance.

Terminology

TermDescription
Multi-lock on gift card balanceSet aside and lock a specific amount from the available balance on a gift card. This ensures that the locked amount is available for a specific time period. You can keep one or more locks active on a gift card at any given time until you have a balance on the gift card. The gift card automatically unlocks when the specified time expires or when you request to unlock and redeem of a multi-lock amount.
Unlock gift card balanceRemove the multi-lock on the gift card balance amount. This does not impact the gift card balance.
Redeem multi-lock amountUnlock and redeem a specific amount from the multi-locked balance on your gift card. The gift card balance is reduced by the redeemed amount.
For example:


- Gift card value: $100
- Locked amount: $75
- Unlocked amount available to spend: $25
- Redeem with unlock to spend: $75
Cashout gift card balanceRemove the remaining balance from a gift card, bringing the account balance to zero (0). The customer may receive the remaining balance in cash, or choose to cash out and deactivate the card or close the gift card account.

Prerequisites

  1. Merchant selects the Gift card payments checkbox under Ecommerce Payments on the Merchant Dashboard. See Clover Merchant Help.
  2. Tokenize the gift card. See Create a gift card token.
  3. Generate an Ecommerce API key or apiAccessKey to use as the Authorization header: Bearer token.

Request gift card balance

  1. Send a POST request to the v1/balance_inquiry endpoint to request the current balance amount on an active gift card.
  2. Enter the required parameter in the request:
FieldTypeDescriptionRequired/Optional
sourcestringSingle-pay Clover gift card token (cToken) indicating the gift card details and metadata.Required.
currencystringThree-letter ISO 4217 currency code.
Format: Lowercase
Length: Maximum 3 characters

Note: If a currency is entered, the balance amount displays in the given currency, as well as the base currency, if different. If no currency is entered, the system uses the base currency.
Optional.

Request and Response example—Retrieve gift card balance

curl  --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/balance_inquiry' \
--header 'authorization: Bearer <authToken>' \
--header 'content-Type: application/json' \
--data-raw '{
   "source": "clv_1TSxxxxxx2S71ECrva7"
}'
{
   "status": "succeeded",
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 5000,
       "new_balance": 5000,
       "lock_amount": 0
   }
}

Request gift card balance with multi-lock

At the time of balance inquiry, you can set aside and lock a specific amount from the available balance on a gift card. This ensures that the locked amount on a gift card is available for a specific time period. To use the locked amount, you need to initiate a redemption unlock.

  1. Send a POST request to the v1/charges endpoint to request the current balance amount on an active gift card.
  2. Enter the required parameter in the request:
FieldTypeDescriptionRequired/Optional
sourcestringSingle-pay Clover gift card token (cToken) indicating the gift card details and metadata.Required.
amountstringAmount to lock on the gift card.Required.
currencystringThree-letter ISO 4217 currency code.
Format: Lowercase
Length: Maximum 3 characters
Required.
capturebooleanFalse. Indicates pre-authorization on a gift card balance and that the charge on the gift card can be captured later using the capture a charge endpoint. Required.
partial_redemptionbooleanTrue. Indicates that the gift card can be charged for a partial amount.Required.

The gift_card object in the Create a charge endpoint returns the metadata, including the multi-lock expiration date, current and new balance, and lock identifier.

Request and Response example—Request gift card balance with multi-lock

curl  --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/charges' \
--header 'authorization: Bearer <authToken>' \
--header 'content-Type: application/json' \
--data-raw '{
   "source": "clv_1TSxxxxxx2S71ECrva7",
   "amount": 100,
   "currency": "usd",
   "capture": "false",
   "partial_redemption": "true",
}'
{
   "id": "ABC123DE45F6G",
   "amount": 100,
   "payment_method_details": "giftCard",
   "amount_refunded": 0,
   "captured": false,
   "ref_num": "151520",
   "outcome": {
       "network_status": "approved_by_network",
       "type": "authorized"
   },
   "status": "succeeded",
   "source": {
       "id": "clv_1TSxxxxxx2S71ECrva7",
       "last4": "5003"
   },
   "partial_auth": true,
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 592,
       "new_balance": 492,
       "lock_id": 251
   }
}

Request unlock and redeem multi-lock gift card balance

You can:

  • Unlock and redeem a specific amount from the multi-locked balance on your gift card.
  • Unlock a card without using the balance amount. In this case, you can send an amount of zero dollars ($0) to the /v1/charges/{chargeId}/capture endpoint.
  1. Send a POST request to the v1/charges/chargeId/capture endpoint to unlock and redeem a multi-locked gift card balance.
  2. Enter the required parameter in the request:
FieldTypeDescriptionRequired/Optional
sourcestringSingle-pay Clover gift card token (cToken) indicating the gift card details and metadata.Required.
amountstringAmount to unlock and redeem from the gift card balance.Required.

The gift_card object in the Capture a charge endpoint returns the metadata, including the multi-lock expiration date, balance, and lock identifier.

Request and Response example—Unlock and redeem multi-lock gift card balance

curl  --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/charges/chargeId/capture' \
--header 'authorization: Bearer <authToken>' \
--header 'content-Type: application/json' \
--data-raw '{
   "amount": "100"
}
{
   "id": "ABC123DE45F6G",
   "amount": 100,
   "payment_method_details": "giftCard",
   "currency": "usd",
   "created": 1680800253000,
   "captured": false,
   "ref_num": "151528",
   "auth_code": "753947",
   "order": "3D7T140NCZ3Z0",
   "outcome": {
       "network_status": "approved_by_network",
       "type": "authorized"
   },
   "paid": true,
   "status": "succeeded",
   "source": {
       "id": "clv_1TSTSBAjam8Fqo1ju5iNq1Tt",
       "brand": "GIFT_CARD",
       "first6": "777732",
       "last4": "5003"
   },
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 592,
       "new_balance": 492,
       "lock_amount": 0,
       "lock_id": 251
   }
}

Request gift card balance cashout

  1. Send a POST request to the /v1/cashout endpoint to remove the remaining balance from the card.
  2. Enter the required parameter in the request:
FieldTypeDescriptionRequired/Optional
sourcestringSingle-pay Clover gift card token (cToken) indicating the gift card details and metadata.Required.

Request and Response example—Request gift card balance cashout

curl  --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/cashout'  
--header 'authorization: Bearer <authToken>'  
--header 'content-Type: application/json'  
--data-raw '{  
   "source": "clv_1TSxxxxxx2S71ECrva7"  
}'
{
  "id": "BCEP5RHDN7REP",
    "amount": 50,
    "ref_num": "018704",
    "outcome": {
        "network_status": "approved_by_network",
        "type": "authorized"
    },
    "paid": true,
    "status": "succeeded",
    "source": {
        "id": "clv_1TSxxxxxx2S71ECrva7",
        "last4": "4965"
    },
    "gift_card": {
        "expiration_date": "2030-01-01",
        "previous_balance": 50,
        "new_balance": 0
    }
}

Related topics