Void and refund for a gift card

North America—United States and Canada

Generate an Ecommerce API key (PAKMS key) Create a gift card token Use the Ecommerce Gift Card API

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:

Refund a redeemed value to an active gift card.
Void a gift card transaction to revert the amount to an active gift card.

Before you begin

Note the following key points:

You must request a void within 24 hours of a gift card transaction; after 24 hours, the amount is refunded instead of voided.
You can only void a multi-lock transaction. Once the multi-lock pre-auth is captured and the unlock and redeem transaction is completed, you can only refund the redeemed amount.
You must request a void for a refund within 24 hours of the refund.

Prerequisites

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

Refund to a gift card

You can refund a redeemed value back to an active gift card. Refunds are usually for merchandise returns or unfulfilled orders where the card was previously charged. This differs from a reload as the customer does not provide funds to add value to the gift card. Clover supports partial refunds on the gift card.

Send a POST request to the v1/refunds endpoint to refund a specified amount to an active gift card.
Enter the required parameter in the request:

Field	Type	Description	Required/Optional
`reason`	string	Reason for the refund. Example: duplicate, fraudulent, or requested_by_customer.	Optional.
`charge`	string	Unique identifier (Id) of the charge to refund. The charge parameter is available in the Get charges and Get a charge endpoints.	Required.

Request and Response example—Refund to a gift card

curl  --request POST \
--url 'https: //scl-sandbox.dev.clover.com/v1/refunds' \
--header 'authorization: Bearer <authToken>' \
--header 'content-Type: application/json' \
--data-raw '{
   "reason": "requested_by_customer",
   "charge": "1ABCDEF23GHIJ"
}'

{
   "id": "AS0NM353ZT5TM",
   "object": "refund",
   "amount": 100,
   "charge": "1ABCDEF23GHIJ",
   "created": 1680799623212,
   "status": "succeeded",
   "metadata": {
       "refundType": "REFUND",
       "authCode": "358939",
       "refNum": "151291",
       "gatewayResponseCode": "00"
   },
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 95,
       "new_balance": 195,
       "lock_amount": 0
   }
}

Void a gift card transaction

You can void a gift card transaction to revert the amount to an active gift card. Void requests are of two types:

Void of redemption or cash out—Reverses a completed purchase or a cash out on a gift card and adds the amount back to the gift card account.
Void of reload or refund—Cancels the reload or refund of an amount to an active card.

Void of redemption or cashout

Send a POST request to the v1/refunds endpoint to void a redeemed amount or a cash out on an active card.
Enter the required parameter in the request:

Field	Type	Description	Required/Optional
`reason`	string	Reason for the refund. Example: duplicate, fraudulent, or requested_by_customer.	Optional.
`charge`	string	Unique identifier (Id) of the charge to refund. The charge parameter is available in the Get charges and Get a charge endpoints.	Required.

Request and Response examples

Void of redeemed amount

curl  --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/refunds'  
--header 'authorization: Bearer <authToken>'  
--header 'content-Type: application/json'  
--data-raw '{  
   "reason": "requested_by_customer",  
   "charge": "1ABCDEF23GHIJ"
}'

{
   "id": "8KCQQM1870S60",
   "object": "refund",
   "amount": 100,
   "charge": "1ABCDEF23GHIJ",
   "created": 1681705213295,
   "status": "succeeded",
   "metadata": {
       "refundType": "VOID",
       "authCode": "350036",
       "refNum": "308198",
       "gatewayResponseCode": "00"
   },
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 400,
       "new_balance": 500,
       "lock_amount": 0
   }
}

Void of cashout

curl  --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/refunds'  
--header 'authorization: Bearer <authToken>'  
--header 'content-Type: application/json'  
--data-raw '{  
   "reason": "requested_by_customer",  
   "charge": "1ABCDEF23GHIJ"
}'

{
   "id": "61V792648Y63Y",
   "object": "refund",
   "amount": 292,
   "charge": "1ABCDEF23GHIJ",
   "created": 1680800800739,
   "status": "succeeded",
   "metadata": {
       "refundType": "VOID",
       "authCode": "698841",
       "refNum": "151901",
       "gatewayResponseCode": "00"
   },
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 0,
       "new_balance": 292,
       "lock_amount": 0
   }
}

Void of a refund

Send a POST request to the /v1/refunds/refundId/cancel endpoint to void a refund.
Enter the required parameter in the request:

Field	Type	Description	Required/Optional
`reason`	string	Reason for the refund. Example: user_cancel.	Required.

Response and Request example—Void of a refund

curl  --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/refunds/{{refundId}}/cancel' \
--header 'authorization: Bearer <authToken>' \
--header 'content-Type: application/json' \
--data-raw '{
   "reason": "USER_CANCEL" 
}'

{  "id": "ABC123DE45F6G",
   "object": "void_on_refund",
   "amount": 100,
   "charge": "1ABCDEF23GHIJ",
   "status": "succeeded",
   "metadata": {
       "refundType": "VOID",
       "authCode": "660762",
       "refNum": "125057",
       "gatewayResponseCode": "00"
   },
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 400,
       "new_balance": 300,
       "lock_amount": 0
   }
}

Void of a reload

Send a POST request to the v1/refunds endpoint to void a reload on an active gift card.
Enter the required parameter in the request:

Field	Type	Description	Required/Optional
`reason`	string	Reason for the refund. Example: duplicate, fraudulent, or requested_by_customer.	Optional.
`charge`	string	Unique identifier (Id) of the charge to refund. The charge parameter is available in the Get charges and Get a charge endpoints.	Required.

Request and Response example—Void of a reload

curl  --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/refunds' \
--header 'authorization: Bearer <authToken>' \
--header 'content-Type: application/json' \
--data-raw '{
   "reason": "requested_by_customer",
   "charge": "1ABCDEF23GHIJ"
}'

{  "id": "ABC123DE45F6G",
   "object": "refund",
   "amount": 500,
   "charge": "1ABCDEF23GHIJ",
   "created": 1681702944579,
   "status": "succeeded",
   "metadata": {
       "refundType": "VOID",
       "authCode": "603796",
       "refNum": "307916",
       "gatewayResponseCode": "00"
   },
   "gift_card": {
       "expiration_date": "2030-01-01",
       "previous_balance": 500,
       "new_balance": 0,
       "lock_amount": 0
   }
}