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.

You can use the complete or partial value on an active gift card for a transaction. If the requested charge amount to use or redeem is greater than the gift card account balance, the account balance is reduced to zero (0). In this case, the gift card account may be closed, and a split tender payment may be requested. A split tender request prompts the customer to pay the difference between the gift card account balance and the requested amount.

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.

Steps

1. Send a POST request to the /v1/charges endpoint to redeem the gift card value.
2. Enter the required parameters in the request based on whether it is a denominated gift card or a non-denominated gift card.

Request and Response examples

Redeem gift card with sufficient balance

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": "true",
   "partial_redemption": "true",
   }

{
   "id": "ABC123DE45F6G",
   "amount": 100,
   "payment_method_details": "giftCard",
   "amount_refunded": 0,
   "captured": true,
   "ref_num": "308196",
   "outcome": {
       "network_status": "approved_by_network",
       "type": "authorized"
   },
   "paid": true,
   "status": "succeeded",
   "source": {
       "id": "clv_1TSxxxxxx2S71ECrva7",
       "last4": "5003"
   },
   "partial_auth": true,
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 500,
       "new_balance": 400
   }
}

Redeem gift card with insufficient balance or non-sufficient funds (NSF)

If the value of a gift card is less than the charge amount, you can request partial approval to redeem the available amount on an active gift card. The request is not declined for insufficient balance, but the account is reduced to 0 (zero) and may be closed.

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": "true",
   "partial_redemption": "false",
}

{
   "id": "CKK5GVZBHB1GA",
   "amount": 10,
   "payment_method_details": "giftCard",
   "amount_refunded": 0,
   "currency": "usd",
   "created": 1681705896145,
   "captured": true,
   "ref_num": "308942",
   "auth_code": "445869",
   "warning_message": "partial_redemption should be true for gift card",
   "outcome": {
       "network_status": "approved_by_network",
       "type": "authorized"
   },
   "paid": true,
   "status": "succeeded",
   "source": {
       "id": "clv_1TSxxxxxx2S71ECrva7",
       "last4": "5003"
   },
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 500,
       "new_balance": 400
   }
}

Related topics

• Use the Ecommerce Gift Card API
• Create a gift card token tutorial
• Activate a gift card tutorial
• Check gift card balance tutorial
• Create a charge endpoint