Walkthrough 1: Sell a Gift Card
This is pre-release documentation for an API in public beta and is subject to change.
This walkthrough provides step-by-step instructions that show how to create a digital gift card and then activate it with an initial balance. The walkthrough includes separate procedures for applications that process gift card orders with the Square Orders and Payments APIs or with a custom order and payment processing system.
To prepare for the walkthrough, you review information about using the Square Sandbox for testing. You also copy the Sandbox access token and location ID for your Square account.
The Square Sandbox is an isolated server environment provisioned for each Sandbox test account. You use your Sandbox access token to create and access account resources in the Sandbox.
In this walkthrough, you create and activate a gift card in the Sandbox. If you follow the procedure that integrates with the Orders API and Payments API, you also create a gift card order and use a test payment token (
cnon:card-nonce-ok) to pay for the order. Sandbox payment methods are easy to use and are never charged. For more information, see Sandbox test values.
In addition, you view gift card status in the Sandbox Seller Dashboard.
This walkthrough creates a digital gift card in the Sandbox. Although testing physical gift cards is not supported in the Sandbox, you can register and activate physical gift cards in the production environment using the process described in this walkthrough.
Follow these steps to get the access token and location ID used in this walkthrough.
Get your Sandbox access token:
At the top of the page, in the Sandbox and Production toggle, choose Sandbox.
On the Credentials page, under Sandbox Access Token, choose Show and then copy the token. All Square API requests require an access token for authorization. This personal access token grants full access to the Sandbox resources in your account.
The Sandbox access token is a secure secret. Do not share it with anyone.
Get your location ID:
In the navigation pane, choose Locations.
On the Locations page, keep Default Test Account selected and copy a location ID.
You are now ready to sell a gift card. To do so, your application creates and processes an order for the gift card amount and then creates and activates the gift card with the initial balance.
This walkthrough provides two separate application flows:
Load a Gift Card Using the Orders API. This procedure shows how to create and activate a gift card when your application uses the Orders API and Payments API to take and process a gift card order.
Load a Gift Card Without the Orders API. This procedure shows how to create and activate a gift card when your application uses a custom order and payment processing system to process a gift card order.