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.
Note
To learn how to use the Square Orders API and Payments API to process the gift card order and payment, see Create and Activate a Gift Card When Using Orders API Integration.
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.
Call CreateGiftCard to create a digital gift card.
Create gift card
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 is0
.{ "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" } }Copy the
id
from the response. You use this value to activate the gift card.
Call CreateGiftCardActivity to activate the gift card with an initial balance. The request must include either
gift_card_id
with the gift card ID orgift_card_gan
with the GAN.This endpoint supports various activity types. For an
ACTIVATE
activity, you provide activity-specific details in theactivate_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
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" ] } } }- For
Optional. Call RetrieveGiftCard to see that the gift card state is set to
ACTIVE
and the balance is $25.Retrieve gift card
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 Square Dashboard, the gift card is reported as activated. Because you are using the Sandbox for testing, you can view the reports in the Sandbox Square Dashboard associated with your Sandbox test account.
- Open the Developer Console.
- In the left pane, choose Sandbox test accounts.
- For Default Test Account, choose Square Dashboard.
- Choose Reports.
- 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 Square 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.