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.

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.

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

   {
     "authentication": {
       "accessToken": "{ACCESS_TOKEN}"
     },
     "bodyParameters": {
       "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

   cURL

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

   {
     "gift_cards": [
       {
         "id": "gftc:012440e514754c42990f3de4527498dc",
         "type": "DIGITAL",
         "gan_source": "SQUARE",
         "state": "ACTIVE",
         "balance_money": {
           "amount": 2500,
           "currency": "USD"
         },
         "gan": "7783320002382646",
         "created_at": "2021-04-11T18:49:34Z",
         "customer_ids": [
           "62Y0FBFDQ0ZHDCGKBYP7FZK474"
         ]
       }
     ]
   }

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're 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. Optional. 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.

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

   cURL

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

   {
     "gift_card_activity": {
       "id": "gcact_e303d6390aae4573a38e8a7027c3f51a",
       "type": "REDEEM",
       "location_id": "S8GWD5R9QB376",
       "created_at": "2021-04-11T19:12:08.000Z",
       "gift_card_id": "gftc:012440e514754c42990f3de4527498dc",
       "gift_card_gan": "7783320002382646",
       "gift_card_balance_money": {
         "amount": 2200,
         "currency": "USD"
       },
       "redeem_activity_details": {
         "amount_money": {
           "amount": 300,
           "currency": "USD"
         },
         "reference_id": "custom-order-id",
         "status": "COMPLETED"
       }
     }
   }

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

   cURL

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

   {
     "gift_card_activity": {
       "id": "gcact_7003b1adf7b042b19499280e2bf82e83",
       "type": "LOAD",
       "location_id": "S8GWD5R9QB376",
       "created_at": "2021-04-11T20:48:51.000Z",
       "gift_card_id": "gftc:012440e514754c42990f3de4527498dc",
       "gift_card_gan": "7783320002382646",
       "gift_card_balance_money": {
         "amount": 3200,
         "currency": "USD"
       },
       "load_activity_details": {
         "amount_money": {
           "amount": 1000,
           "currency": "USD"
         },
         "reference_id": "custom-line-item-id",
         "buyer_payment_instrument_ids": [
           "card-id"
         ]
       }
     }
   }

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

To see the activity history for a gift card, call ListGiftCardActivities using the gift_card_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.

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

Viewing gift card activities in the Seller Dashboard

Square sellers can view gift card activities in the Seller Dashboard. Because you're 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.