Activate a gift card

United States

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.

A purchased gift card is activated before a customer can use it to make payments. There are two types of card activation:

  • Physical gift card activation using the gift card number.
  • Virtual gift card creation and activation using a card activation promotional code.

At the time of gift card purchase, an activation request adds value to the gift card, changes the status of the gift card to active, and returns the necessary information to use the gift card. Both physical and virtual gift cards can be denominated or non-denominated based on whether the gift card has a preset value or not.

Terminology

TermDescription
Physical gift cardTangible gift card that you can load and reload with an amount and use as a cash equivalent for making in-store and online purchases.
Digital or virtual gift cardUnique code or number delivered to a recipient by email, text, or through an app. The virtual card number or promotional code is used for making purchases at online or brick-and-mortar retailers.
Denominated gift cardCards with a specific value assigned to them at the time of purchase. For example, a gift card might be worth $25, $50, or $100. When a customer buys a denominated gift card, they know exactly how much value is on the card.
Non-denominated gift cardsCards without a preset value at the time of purchase are activated with a value determined at the time of purchase. The purchaser or recipient can choose the amount, depending on the terms set by the merchant.
Promotional codeUnique values, usually alphanumeric, associated with a virtual gift card and sent by email, text, or through an app. The promotional or promo code is used to activate and redeem the virtual gift card.

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.

Activate virtual gift card

  1. Send a POST request to the /v1/activate endpoint to create and activate a virtual gift card.
  2. Enter the required parameters in the request based on whether the card is denominated gift card or non-denominated gift card:
FieldTypeDescriptionRequired/Optional
amountintegerAmount activated for the gift card.

- 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 gift card value defined in the promotion code.
Required for non-denominated card.
currencystringThree-letter ISO 4217 currency code.
Format: Lowercase
Length: Maximum 3 characters
Required if the amount is entered.
promotion_codestringVirtual promotional code of the gift card.Required only for virtual gift card activation, if the promotional code is not already configured.

Request and Response examples

Create and activate a denominated, virtual gift 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": "2030-01-01",
        "number": "7777373144600266",
        "previous_balance": 0,
        "new_balance": 5000
    }
}

Create and activate a non-denominated, virtual gift 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": "2030-01-01",
        "number": "7777373191541096",
        "previous_balance": 0,
        "new_balance": 2000
    }
}

Activate physical gift card

  1. Send a POST request to the /v1/activate endpoint to activate a physical gift card.
  2. Enter the required parameters in the request based on whether the card is denominated gift card or non-denominated gift card:
FieldTypeDescriptionRequired/Optional
sourcestringSingle-pay Clover gift card token (token) indicating the gift card details and metadata.Required.
amountintegerAmount activated for the gift card.

- 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 gift card value defined in the promotion code.
Required for non-denominated card.
currencystringThree-letter ISO 4217 currency code.
Format: Lowercase
Length: Maximum 3 characters
Required if the amount is entered.

Request and Response example—Activate a denominated physical card

In this example, activate a physical denominated gift card of $50 value. Only the source parameter is required to activate a denominated physical card, which is the gift card token.

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": "3030-01-01",
        "previous_balance": 0,
        "new_balance": 5000
    }
}

Related topics