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

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:

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:

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:

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:

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

• Use the Ecommerce Gift Card API
• Create a gift card token tutorial
• Request a gift card balance endpoint
• Create a charge endpoint
• Capture a charge endpoint
• Request cashout of gift card balance endpoint