Create and Activate a Gift Card When Using a Custom Processing System

This walkthrough shows how to sell a gift card when your application uses a custom order and payment processing system instead of the Orders API and Payments API. After processing the order to purchase a gift card, you create a gift card and activate it with an initial balance. Because you are using a custom processing system, you specify the balance amount and payment instrument IDs when you activate the card. After the gift card is activated, it's ready for use.

For the purposes of this walkthrough, assume that your application processed a $25 gift card purchase using your custom order and payment processing system.

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:01696eaf3d5141bfb4c7869494257bb6",
       "type": "DIGITAL",
       "gan_source": "SQUARE",
       "state": "PENDING",
       "balance_money": {
         "amount": 0,
         "currency": "USD"
       },
       "gan": "7783320005719034",
       "created_at": "2021-04-11T20:31:43Z"
     }
   }

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 amount_money, specify the amount of money to add to the gift card balance. This example adds $25.
   • For buyer_payment_instrument_ids, specify any card IDs, bank account IDs, or other payment instrument IDs used for the gift card purchase. Square uses this information to perform compliance checks. For this walkthrough, you can use the example values.
   • For reference_id, optionally reference an object from your custom order and payment processing system. For this walkthrough, you can use the example value.

   Create gift card activity

   cURL

   The following is an example response:

   {
     "gift_card_activity": {
       "id": "gcact_e091f58d49b94d149587a94560b24c60",
       "type": "ACTIVATE",
       "location_id": "S8GWD5R9QB376",
       "created_at": "2021-04-11T20:38:49.000Z",
       "gift_card_id": "gftc:01696eaf3d5141bfb4c7869494257bb6",
       "gift_card_gan": "7783320005719034",
       "gift_card_balance_money": {
         "amount": 2500,
         "currency": "USD"
       },
       "activate_activity_details": {
         "amount_money": {
           "amount": 2500,
           "currency": "USD"
         },
         "reference_id": "client-side-payment-id",
         "buyer_payment_instrument_ids": [
           "card-id-1",
           "card-id-2"
         ]
       }
     }
   }

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:01696eaf3d5141bfb4c7869494257bb6",
       "type": "DIGITAL",
       "gan_source": "SQUARE",
       "state": "ACTIVE",
       "balance_money": {
         "amount": 2500,
         "currency": "USD"
       },
       "gan": "7783320005719034",
       "created_at": "2021-04-11T20:31:43Z"
     }
   }

In the Seller Dashboard, the gift card is reported as activated. 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 Activations includes the activity and gift card amount. The gift card is also now listed 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.