Create and Activate a Gift Card When Using Orders API Integration

This walkthrough shows how to sell a Square gift card when your application uses the Orders API and Payments API to process orders and payments. First, you take an order for a gift card using the Orders API and pay for the order using the Payments API. Then, you create a gift card and activate it with an initial balance. After the gift card is activated, it's ready for use.

To enable a buyer to purchase a gift card for themselves or another recipient, you create a gift card order using the Orders API and take payment for the order using the Payments API.

1. Call CreateOrder to create an order for a gift card. In the request, the line item for the gift card must specify an item_type of GIFT_CARD. Otherwise, the order isn't processed as a gift card sale and the subsequent gift card activation 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 activate the gift card.
   • You provide the UID of the gift card line item when you activate the gift card.

1. Generate a secure payment token using the Web Payments SDK or In-App Payments SDK. The payment token represents the card used to pay for an order.

   Note

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

2. Call CreatePayment to take the payment for the order.

   Create payment

   cURL

   In the response, the payment status is set to COMPLETED. Because the order is fully paid, Square also sets the order state to COMPLETED.

At this point, the gift card is reported as pending activation in the Seller Dashboard. Because you are using the Sandbox for testing, you can view the reports in the Sandbox Seller Dashboard associated with your Sandbox test account.

1. Open the Developer Dashboard.
2. In the left pane, choose Sandbox test accounts.
3. For Default Test Account, choose Square Dashboard.
4. Choose Reports.
5. Choose Gift Cards and verify that the report shows the pending activation.

After the buyer pays for the gift card order, you create a gift card using the Gift Cards API and activate the gift card with an initial balance using the Gift Card Activities API.

1. Call CreateGiftCard to create a digital gift card.

   Create gift card

   cURL

   The previous request specifies only the gift card type, which directs Square to generate the gift card account number (GAN). However, providing a custom GAN is also supported.

   Note

   This walkthrough creates a digital gift card in the Sandbox. Although testing physical gift cards isn't supported in the Sandbox, you can register and activate physical gift cards in the production environment using the process described in this walkthrough.

   The following example response shows the gift card state is PENDING and the current balance is 0:

   {
     "gift_card": {
       "id": "gftc:012440e514754c42990f3de4527498dc",
       "type": "DIGITAL",
       "gan_source": "SQUARE",
       "state": "PENDING",
       "balance_money": {
         "amount": 0,
         "currency": "USD"
       },
       "gan": "7783320002382646",
       "created_at": "2021-04-11T18:49:34Z"
     }
   }

2. Copy the id from the response. You use this value to activate the gift card.

1. Call CreateGiftCardActivity to activate the gift card with an initial 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 an ACTIVATE activity, you provide activity-specific details in the activate_activity_details field:

   • For order_id, specify the ID of the associated 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 balance.

   Create gift card activity

   cURL

   The following is an example response:

   {
     "gift_card_activity": {
       "id": "gcact_c24da663c0d242f5a29837d8e165bf97",
       "type": "ACTIVATE",
       "location_id": "S8GWD5R9QB376",
       "created_at": "2021-04-11T19:01:14.000Z",
       "gift_card_id": "gftc:012440e514754c42990f3de4527498dc",
       "gift_card_gan": "7783320002382646",
       "gift_card_balance_money": {
         "amount": 2500,
         "currency": "USD"
       },
       "activate_activity_details": {
         "amount_money": {
           "amount": 2500,
           "currency": "USD"
         },
         "order_id": "q8vfn99RLTr7FuMaUtuDG6RHdCcZY",
         "line_item_uid": "syHOf0zv9OjS2vhkhFozVC"
       }
     }
   }

2. Optional. Call RetrieveGiftCard to see that the gift card state is set to ACTIVE and the balance is $25.

   Retrieve gift card

   cURL

   The following is an example response:

   {
     "gift_card": {
       "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"
     }
   }

Now that the gift card is activated, you can open the Gift Cards reports page in the Sandbox Seller Dashboard and verify that the activity and gift card amount are listed under Activations. In addition, the gift card is now listed on the Overview page in the Gift Cards section of the Sandbox Seller Dashboard.

Buyers can purchase a gift card for themselves or for another recipient. The Gift Cards API doesn't provide email support, so your application must handle the delivery of the gift card information. For example, your application might choose to:

• Show gift card information on your application's website.
• Email gift card information to the recipient.

Continue to Walkthrough 2: Use a Gift Card and learn how to pay for an order using an activated gift card.

In addition, you can explore the Gift Cards and Gift Card Activities APIs in other ways. For example, you can try out the Gift Cards sample (Node.js) or build and send API requests from API Explorer using your Sandbox access token.