Use the Gift Card API
What is a gift card
A gift card is a prepaid payment card used to make purchases at participating restaurants, stores, or online retailers. A gift card can have different denominations. You can redeem the value of these cards for services, merchandise, or even cash, depending on the terms and conditions set by the card issuer.
Clover Gift Cards 💳
You can:
-
Use Clover Gift Card Solutions to check out online or in person at the point of sale (POS). This is a native gift card with an SCV (security code value) that uses the integrated gift card solution payment gateway from Fiserv.
-
Use a non-native gift card with an FCA (foreign access code). A non-Fiserv gift card or a gift card that does not use the Fiserv payment gateway.
-
Use the purchase or split tender feature to start the transaction with a gift card and complete the transaction with another credit or debit card.
-
Use the Gift Card API to perform the following actions:
- Activation
- Balance inquiry
- Redeem
- Reload
- Cashout
- Refund or void a transaction
Use the Clover Gift Card API
Prerequisites for merchants
- Set up gift card tiers in Gift Solutions. For merchants who use the Clover device, configure a merchant account for the gift card tiers in Clover Gift Card Solutions to enable the processing of gift cards. The Clover server synchronizes the order data with the merchant's Clover devices. You can use the gift card endpoint to leverage the gift card features added to Clover payment solutions.
- Your merchant needs to sign up for Clover Gift Cards for gift card plans.
Prerequisites to use Clover Gift Cards APIs
- Get an OAuth token and generate an Ecommerce API key.
- Create a gift card token, for example:
clv_1TSxxxxxx2S71ECrva7
Use the Clover Gift Card API
Step 1: Generate or retrieve API key
curl --request GET \
--url 'https://dev1.dev.clover.com/pakms/apikey'
--header 'authorization: Bearer <Token>'
Step 2: Generate a token for the gift card using /v1/tokens
Clover receives the gift card number and SCV (security code value associated with the gift card) from the Clover token in an encrypted format.
Example:
curl --request POST \
--url 'https://token-sandbox.dev.clover.com/v1/tokens' \
--header 'apiKey: <apikey>' \
--header 'content-Type: application/json' \
--data-raw '{
"gift_card": {
"number": "98765441066",
"security_code": "785577",
"foreign_access_code": "67755"
}
}'
Gift Card token API request parameters
Field | Description | Required/Optional |
---|---|---|
number | Gift card number. Length: One of the following: 6-digit, 13-digit, 16-digit, or 19-digit | Required |
security_code | Encrypted security code associated with the gift card. Length: 4-8 characters | Optional |
foreign_access_code | Foreign access code for merchants converting to CLGC (closed loop gift card) from an external gift card program, if applicable. | Optional |
Activate gift card
This transaction creates and activates a new gift card and returns the necessary information to use the account.
- If the card is non-denominated, the amount is required.
- If the card is denominated, the amount field is optional.
- If the amount is entered, it must match the card's value defined in the promotion code.
Activate virtual gift card
Use the /v1/activate
endpoint to create and activate a virtual gift card.
Example: Ecomm virtual activation API request and response samples for creating and activating a denominated card:
curl --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/activate' \
--header 'authorization: Bearer <token>' \
--header 'content-Type: application/json' \
--data '{
"promotion_code": "67062"
}'
{
"id": "ABC123DE45F6G",
"amount": 5000,
"ref_num": "022001",
"outcome": {
"network_status": "approved_by_network",
"type": "authorized"
},
"paid": true,
"status": "succeeded",
"source": {
"last4": "0266"
},
"gift_card": {
"security_card_value": "75537209",
"expiration_date": "3025-01-01",
"number": "7777373144600266",
"previous_balance": 0,
"new_balance": 5000
}
}
Example: Ecomm virtual activation API request and response for creating and activating a non-denominated card:
curl --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/activate' \
--header 'authorization: Bearer<token>' \
--header 'content-Type: application/json' \
--data '{
"promotion_code": "67063",
"amount": 2000,
"currency": "usd"
}
{
"id": "ABC123DE45F6G",
"amount": 2000,
"ref_num": "021717",
"outcome": {
"network_status": "approved_by_network",
"type": "authorized"
},
"paid": true,
"status": "succeeded",
"source": {
"last4": "1096"
},
"gift_card": {
"security_card_value": "3256",
"expiration_date": "3025-01-01",
"number": "7777373191541096",
"previous_balance": 0,
"new_balance": 2000
}
}
Activate physical gift card
Use the v1/activate
endpoint to activate an inactive physical gift card. Send a POST request to v1/activate
endpoint.
Example: Activate a physical denominated gift card of $50 value.
curl --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/activate' \
--header 'authorization: Bearer <token>' \
--header 'content-Type: application/json' \
--data-raw '{
"source": "clv_1TSxxxxxx2S71ECrva7"
}'
{
"id": "ABC123DE45F6G",
"amount": 5000,
"ref_num": "201108",
"outcome": {
"network_status": "approved_by_network",
"type": "authorized"
},
"paid": true,
"status": "succeeded",
"source": {
"last4": "9585"
},
"gift_card": {
"expiration_date": "3025-01-01",
"previous_balance": 0,
"new_balance": 5000
}
}
Activate gift card request parameters
Field | Description | Required/Optional |
---|---|---|
source | Tokenized card (cToken ) that is saved as a card on file (COF) for future transactions. | Required |
amount | Amount activated for the gift card in local currency. | Required |
currency | Three-letter ISO 4217 currency code. Format: Lowercase Length: Maximum 3 | Required |
promotion_code | Virtual promotional code of the gift card. Note: Applicable only for gift card virtual activation if the promo code is not already configured. | Optional |
Reload an active gift card
Use the /v1/reload
endpoint to reload an amount to an active gift card account.
Example:
curl --request POST \
--url 'https://scl-sandbox.dev.clover.com/v1/reload' \
--header 'authorization: Bearer <authToken>' \
--header 'content-Type: application/json' \
--data-raw '{
"source": "clv_1TSxxxxxx2S71ECrva7",
"amount": 500,
"currency": "usd",
}'
{
"id": "ABC123DE45F6G",
"amount": 500,
"ref_num": "151415",
"outcome": {
"network_status": "approved_by_network",
"type": "authorized"
},
"paid": true,
"status": "succeeded",
"source": {
"id": "clv_1TSxxxxxx2S71ECrva7",
"last4": "5003"
},
"gift_card": {
"expiration_date": "3025-01-01",
"previous_balance": 92,
"new_balance": 592
}
}
Reload gift card request parameters
Field | Description | Required/Optional |
---|---|---|
source | Tokenized card (cToken ) that is saved as a card on file (COF) for future transactions. | Required |
amount | Amount activated for the gift card in local currency. | Required |
currency | Three-letter ISO 4217 currency code. Format: Lowercase Length: Maximum 3 | Required |
Request gift card balance
Use the /v1/balance_inquiry
endpoint to request the current balance of an active gift card account.
Example:
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": "2025-01-01",
"previous_balance": 5000,
"new_balance": 5000,
"lock_amount": 0
}
}
Balance inquiry gift card request parameters
Field | Description | Required/Optional |
---|---|---|
source | Tokenized card (cToken ) that is saved as a card on file (COF) for future transactions. | Required |
Request gift card balance with multi-lock
Multi-lock allows you to:
- Lock a requested amount up to the current available balance of the gift card or up to the requested amount for a preset time.
- 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 the preset value for use when:
- The preset multi-lock time expires.
-or- - A POST request for Redemption Unlock with multi-lock is sent to
/v1/charges
.
- The preset multi-lock time expires.
Example:
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": "2025-01-01",
"previous_balance": 592,
"new_balance": 492,
"lock_id": 251
}
}
Redeem gift card for insufficient balance (non-sufficient funds)
If a gift card value is less than the charge amount, you can request partial approval to redeem the available amount on an active gift card account. Use /v1/charges
to redeem the gift card value.
Note: A decline is not given for insufficient funds. If the requested amount exceeds the account balance, the account is reduced to 0 (zero) and may be closed.
Examples:
Redemption for 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",
"return_gateway_response": "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": "2025-01-01",
"previous_balance": 500,
"new_balance": 400
}
}
Redemption for insufficient 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": "false",
"return_gateway_response": "true"
}
{
"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": "2025-01-01",
"previous_balance": 500,
"new_balance": 400
}
}
Request redemption unlock with multi-lock
After a Balance Inquiry with a multi-lock transaction, you can complete the purchase on a gift card and unlock any remaining balance from the transaction. The amount to redeem is removed from the balance of the gift card. To unlock a gift card without affecting the balance, send 0 (zero), use /v1/charges/{chargeId}/capture
endpoint.
Example:
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": "2025-01-01",
"previous_balance": 592,
"new_balance": 492,
"lock_amount": 0,
"lock_id": 251
}
}
Refund to a gift card
Use /v1/refunds
endpoint to refund the value back to the card. This differs from a reload as the customer does not provide funds to add value. This transaction is usually used for merchandise returns or unfulfilled orders where the card was previously charged.
Example:
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"
}'
Refund of a gift card request parameters
Field | Description | Required/Optional |
---|---|---|
charge | Unique identifier (ID) of the charge to refund. The charge parameter is available in the get charges and get a charge endpoints. | Required |
Void of redemption or cashout
Use v1/refunds
endpoint to void a redemption or cashout.
Example:
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"
}'
Void of redemption a gift card request parameters
Field | Description | Required/Optional |
---|---|---|
charge | Unique identifier (ID) of the charge to refund. The charge parameter is available in the get charges and get a charge endpoints. | Required |
Void of reload or refund
Use /v1/refunds/refundId/cancel
endpoint for the void of refund.
Examples:
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": "2025-01-01",
"previous_balance": 400,
"new_balance": 300,
"lock_amount": 0
}
}
Use /v1/refunds
endpoint for the void of 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": "2025-01-01",
"previous_balance": 500,
"new_balance": 0,
"lock_amount": 0
}
}
Void of reload or refund a gift card request parameters
Field | Description | Required/Optional |
---|---|---|
charge | Unique identifier (ID) of the charge to refund. The charge parameter is available in the get charges and get a charge endpoints. | Required |
Request gift card balance cashout
Use /v1/cashout
endpoint to create a cashout request to remove the remaining balance from the card.
Example:
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"
}'
Cashout a gift card request parameters
Field | Description | Required/Optional |
---|---|---|
source | Tokenized card (cToken ) that is saved as a card on file (COF) for future transactions. | Required |
Updated 12 days ago