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.
Did you know?
Watch the Sandbox 101: Gift Cards API video to see how to purchase, create, and activate a gift card using steps that are similar to this walkthrough. You can also check out the Gift Cards API Sample App and the accompanying Gift Cards API Sample App Overview video to see how you can create and manage gift cards in a Node.js application.
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.
Note
To learn how to create and activate a gift card when your application uses a custom order and payment processing system, see Create and Activate a Gift Card When Using a Custom Processing System.
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
ofGIFT_CARD
. Otherwise, the order isn't processed as a gift card sale and the subsequent gift card activation doesn't succeed.Create order
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.
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 theCreatePayment
request in the next step.Call CreatePayment to take the payment for the order.
Create payment
In the response, the payment status is set to
COMPLETED
. Because the order is fully paid, Square also sets the order state toCOMPLETED
.
At this point, the gift card is reported as pending activation in the Square Dashboard. 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 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.
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 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" } }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
order_id
, specify the ID of the associated order. The order state must beCOMPLETED
. - 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
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" } } }- 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: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 Square 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 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.