Redeem and Reload a Gift Card When Using Orders API and Payments API Integration

This walkthrough shows how to redeem and reload a Square gift card when your application uses the Orders API and Payments API to process orders and payments. The walkthrough assumes that you completed Walkthrough 1: Sell a Gift Card and have an activated gift card.

When using the Payments API to take a gift card payment, the source_id of your CreatePayment request can specify either a gift card ID or a payment token generated from the Web Payments SDK or In-App Payments SDK.

This walkthrough provides procedures for both options:

• Option 1: Create a payment using a gift card ID
• Option 2: Create a payment using a payment token

The following procedure shows a typical application flow for accepting a payment from a gift card on file when your application uses the Orders API and Payments API. First, you list the gift cards on file for the customer, create an order, and create the payment. After the payment is completed, Square automatically updates the gift card balance.

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.

5. Copy the id of the selected gift card. You use this ID when you create the payment.

Create the order

1. Call CreateOrder to create an order.

   Create order

   cURL

2. Copy the id of the order from the response. You use this ID when you create the payment.

Create the payment

1. Call CreatePayment to pay for the order using the gift card ID. Specify the gift card ID for source_id and the order ID for order_id.

   Create payment

   cURL

   The response should show that the payment status is COMPLETED and the card_details status is CAPTURED. Note that Square also supports taking partial payments with Square gift cards.

   When you use the Payments API to process the payment, Square automatically creates a REDEEM activity that updates the gift card balance after the payment is successfully completed.

2. Optional. Retrieve the gift card and get the updated balance to display to the buyer.

The following procedure shows a typical application flow for using the Web Payments SDK or In-App Payments SDK to take a gift card payment. First, you create an order, generate a payment token, and create the payment. After the payment is completed, Square automatically updates the gift card balance.

Create the order

1. Call CreateOrder to create an order.

   Create order

   cURL

2. Copy the id of the order from the response. You use this ID when you create the payment.

Generate the payment token

1. After the buyer enters the gift card account number (GAN) in your payment form, the Web Payments SDK or In-App Payments SDK generates a secure payment token for the gift card. For more information, see Take a Gift Card Payment (Web Payments SDK) or Gift Card Payments (In-App Payments SDK).

   Note

   For this walkthrough, you skip this step and use a test payment token for your CreatePayment request in the next step.

   Test payment tokens cannot be used to retrieve a gift card, so you also skip the optional step of calling RetrieveGiftCardFromNonce to get the gift card balance and state before creating the payment.

Create the payment

1. Call CreatePayment to pay for the order using the payment token. Specify the order ID for order_id. Note that the cnon:gift-card-nonce-ok value specified for source_id is the test payment token for a Sandbox gift card.

   Create payment

   cURL

   The response should show that the payment status is COMPLETED and the card_details status is CAPTURED. Note that Square also supports taking partial payments with Square gift cards.

   When you use the Payments API to process the payment, Square automatically creates a REDEEM activity that updates the gift card balance after the payment is successfully completed.

2. Optional. Retrieve the gift card and get the updated balance to display to the buyer.

   Note

   For this walkthrough, you skip this step. The test payment token used for the CreatePayment request isn't associated with your gift card, so the balance wasn't updated.

   Calling the RetrieveGiftCardFromNonce endpoint in the production environment enables you to retrieve a gift card using a payment token. Neither the Web Payments SDK, In-App Payments SDK, nor CreatePayment response expose the gift card ID or full GAN.

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 the Orders API and Payments API. First, you create an order for the amount to add to the gift card, generate a payment token, and create the payment. After the payment is completed, you create a LOAD activity and provide the order and line item IDs.

Create the order

1. Call CreateOrder to create an order for the amount to add to the gift card. In the order, the line item for the gift card funds must specify an item_type of GIFT_CARD. Otherwise, the order isn't processed as a gift card order and the corresponding LOAD activity doesn't succeed.

   Create order

   cURL

2. Copy the id of the order and the uid of the GIFT_CARD line item from the response.

   • You provide the ID of the order when you pay for the order and load the gift card.
   • You provide the UID of the GIFT_CARD line item when you load the gift card.

Generate the payment token

1. After the buyer enters the credit card number in your payment form, the Web Payments SDK or In-App Payments SDK generates a secure payment token for the credit card.

   Note

   For this walkthrough, you skip this step and use a test payment token as the source_id for your CreatePayment request in the next step.

Create the payment

1. Call CreatePayment to pay for the order. Specify the order ID for order_id. Note that the cnon:card-nonce-ok value specified for source_id is the test payment token for a Sandbox credit card.

   Create payment

   cURL

   The response should show that the payment status is COMPLETED and the card_details status is CAPTURED. Because the order is now fully paid, Square sets the order state to COMPLETED.

Create a LOAD activity to update the gift card balance

1. Call CreateGiftCardActivity to update the gift card balance. The request must include either the gift_card_id with the gift card ID or the 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 order_id, specify the ID of the order. The order state must be COMPLETED.
   • For line_item_uid, specify the UID of the gift card line item. Square reads the order information to determine the amount to add to the gift card.

   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_add1aab7693e4fa6891d0597ee3f63dd",
       "type": "LOAD",
       "location_id": "S8GWD5R9QB376",
       "created_at": "2021-04-11T19:21:59.000Z",
       "gift_card_id": "gftc:01696eaf3d5141bfb4c7869494257bb6",
       "gift_card_gan": "7783320005719034",
       "gift_card_balance_money": {
         "amount": 1901,
         "currency": "USD"
       },
       "load_activity_details": {
         "amount_money": {
           "amount": 1000,
           "currency": "USD"
         },
         "order_id": "UXEmEo3X5XYPyfKIrB4tde4LupGZY",
         "line_item_uid": "m2nFRgmD4AhdUmDxmDhRBC"
       }
     }
   }

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 Square Dashboard

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

1. Open the Developer Console.

2. In the Sandbox Test Accounts section, choose Open next to Default Test Account. This opens the Sandbox Square 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.