Learn how to redeem and reload a Square gift card using the Gift Card Activities API when your application uses a custom order and payment processing system.
Gift Cards API: Walkthrough 2

Redeem and Reload a Gift Card When Using a Custom Processing System

This walkthrough shows how to redeem and reload a gift card when your application uses a custom order and payment processing system. The walkthrough assumes that you completed Walkthrough 1: Sell a Gift Card and have an activated gift card.

Note

To learn how to redeem or reload a gift card when your application integrates with the Orders API and Payments API, see Redeem and Reload a Gift Card When Using Orders API and Payments API Integration.

The following procedure shows a typical application flow for accepting a payment when your application uses a custom payment processing system. If your application supports gift card on file payments, first list the gift cards on file. Gift cards on file are made available by linking customer profiles to gift cards, which requires integration with the Customers API. After creating and processing the order and payment, you must call CreateGiftCardActivity in the Gift Card Activities API and create a REDEEM activity.

List gift cards on file

Before you begin, make sure that you linked a customer to the gift card.

Note

Linking a customer profile to a gift card is only required to follow the steps in this walkthrough that take a payment from a gift card on file.

Alternatively, to get the gift card ID to use for your custom payment processing, your application can collect the gift card account number (GAN) from the buyer and call RetrieveGiftCardFromGAN.

  1. If needed, call SearchCustomers to find the customer profile for the buyer. You can search by phone number, email address, and other supported query filters. For example, if the buyer signs in to your application using an email address, you can use the following request:

    Search Customers
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    curl https://connect.squareup.com/v2/customers/search \
      -X POST \
      -H 'Square-Version: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "query": {
          "filter": {
            "email_address": {
              "exact": "{EMAIL_ADDRESS}"
            }
          }
        }
      }'
  2. Copy the id of the customer profile from the response. You use this ID to list the gift cards on file for the buyer in the next step.

  3. Call ListGiftCards and specify the ID of the customer profile for the customer_id query parameter:

    List Gift Cards
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/gift-cards?customer_id={{customer_id}} \
      -H 'Square-Version: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    The following example response contains one gift card, which means that the buyer has only one gift card on file:

  4. Allow the buyer to confirm or select the gift card they want to use for payment. For example, for each linked gift card in the ACTIVE state, display the last four digits of the GAN along with the gift card balance.

If you are not taking a payment from a gift card on file, you can collect the GAN from the buyer.

Process the order and payment

  1. Create an order using your custom processing system.

  2. Check the gift card balance and state by calling RetrieveGiftCard using the gift card ID or RetrieveGiftCardFromGAN using the GAN that you collected from the buyer.

  3. Take a payment from the gift card using your custom processing system. For this walkthrough, assume that you processed a $3 gift card payment.

    Note

    If you are using the Payments API with a custom ordering system, Square updates the balance when the payment is completed so you can skip the next step.

Create a REDEEM activity to update the gift card balance

  1. Call CreateGiftCardActivity to update the gift card balance. The request must include either gift_card_id with the gift card ID or gift_card_gan with the GAN.

    This endpoint supports various activity types. For a REDEEM activity, you provide related details in the redeem_activity_details field:

    • For amount_money, specify the amount to deduct from the gift card balance. This example deducts $3.

    • For reference_id, optionally reference an object from your custom processing system, such as the ID of the associated order.

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_gan": "{GIFT_CARD_ACCOUNT_NUMBER}",
          "type": "REDEEM",
          "location_id": "{LOCATION_ID}",
          "redeem_activity_details": {
            "amount_money": {
              "amount": 300,
              "currency": "USD"
            },
            "reference_id": "custom-order-id"
          }
        }
      }'

    The following example response shows the updated gift card balance and the amount that was redeemed:

  2. Optional. Show the updated balance to the buyer.

For this walkthrough scenario, the buyer wants to add money to the gift card balance after redeeming the gift card for a purchase. Buyers can load additional funds onto gift cards that are in an ACTIVE state. After collecting the funds from the buyer, you must call CreateGiftCardActivity in the Gift Card Activities API and create a LOAD activity that updates the gift card balance.

The following procedure shows a typical application flow for reloading a gift card when your application uses a custom system to process orders and payments. First, you create an order for the amount to add to the gift card and then create the payment. After the payment is completed, you create a LOAD activity and provide the amount to add to the gift card, any payment instrument IDs, and an optional reference ID.

Process the order and payment

  1. Create an order using your custom processing system. This order defines the amount the buyer wants to add to the gift card.

  2. Take a payment from the gift card using your custom processing system. For this walkthrough, assume that you processed a $10 payment.

Create a LOAD activity to update the gift card balance

  1. Call CreateGiftCardActivity to update the gift card balance. The request must include either gift_card_id with the gift card ID or gift_card_gan with the GAN. If needed, you can collect the GAN from the buyer.

    This endpoint supports various activity types. For a LOAD activity, you provide related details in the load_activity_details field:

    • For amount_money, specify the amount to add to the gift card. For this walkthrough, the amount is $10.

    • For buyer_payment_instrument_ids, specify any payment instrument IDs (such as a card ID or bank account ID) that was used for the payment. Square uses this information to perform compliance checks. For this walkthrough, you can use the example value.

    • For reference_id, optionally reference an object from your custom processing system, such as the ID of the line item for the gift card amount.

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_gan": "{GIFT_CARD_ACCOUNT_NUMBER}",
          "type": "LOAD",
          "location_id": "{LOCATION_ID}",
          "load_activity_details": {
            "amount_money": {
              "amount": 1000,
              "currency": "USD"
            },
            "buyer_payment_instrument_ids": [
              "card-id"
            ],
            "reference_id": "custom-line-item-id"
          }
        }
      }'

    The following example response shows the updated gift card balance and the amount that was added:

  2. Optional. Show the updated balance to the buyer.

To see the activity history for a gift card, call ListGiftCardActivities using the giftcard_id query parameter. If needed, you can call RetrieveGiftCardFromGAN, RetrieveGiftCardFromNonce, or ListGiftCards to get the gift card ID.

The following example request lists all activities for the specified gift card. By default, the response returns a maximum page size of 50 activities.

List Gift Card Activities
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/gift-cards/activities?gift_card_id={{gift_card_id}} \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

You can optionally use other query parameters to sort the activities and filter by activity type, location, and reporting period.

Note

If you encounter issues when running the cURL command from a terminal window, try wrapping the endpoint URL in quotation marks and resending the request.

Viewing gift card activities in the Seller Dashboard

Square sellers can view gift card activities in the Seller Dashboard. Because you are testing this walkthrough in the Sandbox, you can review gift card activities in the Sandbox Seller Dashboard.

  1. Open the Developer Dashboard.

  2. In the Sandbox Test Accounts section, choose Open next to Default Test Account. This opens the Sandbox Seller Dashboard associated with the default test account.

  3. In the left pane, choose Gift Cards.

  4. On the Overview page, select the gift card from the list. A pane opens to display the gift card details and list of activities.

    You can search for a particular gift card by entering the full GAN in the Search by Gift Card Number box.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.