This walkthrough shows how to redeem and reload a gift card when your application uses a custom order and payment processing system. The walkthrough assumes that you completed Walkthrough 1: Sell a Gift Card and have an activated gift card.
Note
To learn how to redeem or reload a gift card when your application integrates with the Orders API and Payments API, see Redeem and Reload a Gift Card When Using Orders API and Payments API Integration.
The following procedure shows a typical application flow for accepting a payment when your application uses a custom payment processing system. If your application supports gift card on file payments, first list the gift cards on file. Gift cards on file are made available by linking customer profiles to gift cards, which requires integration with the Customers API. After creating and processing the order and payment, you must call CreateGiftCardActivity
in the Gift Card Activities API and create a REDEEM
activity.
List gift cards on file
Before you begin, make sure that you linked a customer to the gift card.
Note
Linking a customer profile to a gift card is only required to follow the steps in this walkthrough that take a payment from a gift card on file.
Alternatively, to get the gift card ID to use for your custom payment processing, your application can collect the gift card account number (GAN) from the buyer and call RetrieveGiftCardFromGAN.
If needed, call SearchCustomers to find the customer profile for the buyer. You can search by phone number, email address, and other supported attributes. For example, if the buyer signs in to your application using an email address, you can use the following request:
{ "authentication": { "accessToken": "{ACCESS_TOKEN}" }, "bodyParameters": { "query": { "filter": { "email_address": { "exact": "{EMAIL_ADDRESS}" } } } } }Copy the
id
of the customer profile from the response. You use this ID to list the gift cards on file for the buyer in the next step.Call ListGiftCards and specify the ID of the customer profile for the
customer_id
query parameter:List gift cards
The following example response contains one gift card, which means that the buyer has only one gift card on file:
{ "gift_cards": [ { "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", "customer_ids": [ "62Y0FBFDQ0ZHDCGKBYP7FZK474" ] } ] }Allow the buyer to confirm or select the gift card they want to use for payment. For example, for each linked gift card in the
ACTIVE
state, display the last four digits of the GAN along with the gift card balance.
If you're not taking a payment from a gift card on file, you can collect the GAN from the buyer.
Process the order and payment
Create an order using your custom processing system.
Optional. Check the gift card balance and state by calling RetrieveGiftCard using the gift card ID or RetrieveGiftCardFromGAN using the GAN that you collected from the buyer.
Take a payment from the gift card using your custom processing system. For this walkthrough, assume that you processed a $3 gift card payment.
Note
If you're using the Payments API with a custom ordering system, Square updates the balance when the payment is completed so you can skip the next step.
Create a REDEEM activity to update the gift card balance
Call CreateGiftCardActivity to update the gift card 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 a
REDEEM
activity, you provide related details in theredeem_activity_details
field:- For
amount_money
, specify the amount to deduct from the gift card balance. This example deducts $3. - For
reference_id
, optionally reference an object from your custom processing system, such as the ID of the associated order.
Create gift card activity
The following example response shows the updated gift card balance and the amount that was redeemed:
{ "gift_card_activity": { "id": "gcact_e303d6390aae4573a38e8a7027c3f51a", "type": "REDEEM", "location_id": "S8GWD5R9QB376", "created_at": "2021-04-11T19:12:08.000Z", "gift_card_id": "gftc:012440e514754c42990f3de4527498dc", "gift_card_gan": "7783320002382646", "gift_card_balance_money": { "amount": 2200, "currency": "USD" }, "redeem_activity_details": { "amount_money": { "amount": 300, "currency": "USD" }, "reference_id": "custom-order-id", "status": "COMPLETED" } } }- For
Optional. Show the updated balance to the buyer.
For this walkthrough scenario, the buyer wants to add money to the gift card balance after redeeming the gift card for a purchase. Buyers can load additional funds onto gift cards that are in an ACTIVE
state. After collecting the funds from the buyer, you must call CreateGiftCardActivity
in the Gift Card Activities API and create a LOAD
activity that updates the gift card balance.
The following procedure shows a typical application flow for reloading a gift card when your application uses a custom system to process orders and payments. First, you create an order for the amount to add to the gift card and then create the payment. After the payment is completed, you create a LOAD
activity and provide the amount to add to the gift card, any payment instrument IDs, and an optional reference ID.
Process the order and payment
Create an order using your custom processing system. This order defines the amount the buyer wants to add to the gift card.
Take a payment from the gift card using your custom processing system. For this walkthrough, assume that you processed a $10 payment.
Create a LOAD activity to update the gift card balance
Call CreateGiftCardActivity to update the gift card balance. The request must include either
gift_card_id
with the gift card ID orgift_card_gan
with the GAN. If needed, you can collect the GAN from the buyer.This endpoint supports various activity types. For a
LOAD
activity, you provide related details in theload_activity_details
field:- For
amount_money
, specify the amount to add to the gift card. For this walkthrough, the amount is $10. - For
buyer_payment_instrument_ids
, specify any payment instrument IDs (such as a card ID or bank account ID) that was used for the payment. Square uses this information to perform compliance checks. For this walkthrough, you can use the example value. - For
reference_id
, optionally reference an object from your custom processing system, such as the ID of the line item for the gift card amount.
Create gift card activity
The following example response shows the updated gift card balance and the amount that was added:
{ "gift_card_activity": { "id": "gcact_7003b1adf7b042b19499280e2bf82e83", "type": "LOAD", "location_id": "S8GWD5R9QB376", "created_at": "2021-04-11T20:48:51.000Z", "gift_card_id": "gftc:012440e514754c42990f3de4527498dc", "gift_card_gan": "7783320002382646", "gift_card_balance_money": { "amount": 3200, "currency": "USD" }, "load_activity_details": { "amount_money": { "amount": 1000, "currency": "USD" }, "reference_id": "custom-line-item-id", "buyer_payment_instrument_ids": [ "card-id" ] } } }- For
Optional. Show the updated balance to the buyer.
To see the activity history for a gift card, call ListGiftCardActivities using the gift_card_id
query parameter. If needed, you can call RetrieveGiftCardFromGAN, RetrieveGiftCardFromNonce, or ListGiftCards to get the gift card ID.
The following example request lists all activities for the specified gift card. By default, the response returns a maximum page size of 50 activities.
List gift card activities
You can optionally use other query parameters to sort the activities and filter by activity type, location, and reporting period.
Note
If you encounter issues when running the cURL command from a terminal window, try wrapping the endpoint URL in quotation marks and resending the request.
Viewing gift card activities in the Seller Dashboard
Square sellers can view gift card activities in the Seller Dashboard. Because you're testing this walkthrough in the Sandbox, you can review gift card activities in the Sandbox Seller Dashboard.
Open the Developer Dashboard.
In the Sandbox Test Accounts section, choose Open next to Default Test Account. This opens the Sandbox Seller Dashboard associated with the default test account.
In the left pane, choose Gift Cards.
On the Overview page, select the gift card from the list. A pane opens to display the gift card details and list of activities.
You can search for a particular gift card by entering the full GAN in the Search by Gift Card Number box.