Overview

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.

Steps

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

Field	Type	Description	Required/Optional
`source`	string	Single-pay Clover gift card token (token) indicating the gift card details and metadata.	Required.
`amount`	integer	Amount to redeem on the gift card.	Required.
`currency`	string	Three-letter ISO 4217 currency code. Format: Lowercase Length: Maximum 3 characters	Required.
`capture`	boolean	Set as True to immediately capture the amount to redeem on the gift card.	Optional.
`partial_redemption`	boolean	Set as: True to redeem a partial amount on the gift card balance. False to redeem the complete gift card balance.	Optional.

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
   }
}

Redeem a gift card

Overview

Steps

Request and Response examples

Redeem gift card with sufficient balance

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

Related topics