Applies to: Gift Cards API | Gift Card Activities API | Orders API | Locations API | Payments API | Web Payments SDK | In-App Payments SDK
Learn how to redeem a Square gift card for a purchase using the Payments API or the Gift Card Activities API.
Square gift cards can be redeemed at any business location of the seller who issued the gift card. A gift card must be in the ACTIVE
state to pay for a purchase.
Developers can use Square APIs to redeem gift cards for purchases. The steps for redeeming a gift card depend on how your application processes payments:
Payments API integration - If your application uses the Payments API to process payments, Square automatically updates the gift card balance after the
CreatePayment
request is completed. For more information, see Redeem a gift card when using the Payments API.Custom payment processing - If your application doesn't use the Payments API to process payments, you must call
CreateGiftCardActivity
to create aREDEEM
activity after the payment is completed. For more information, see Redeem a gift card when using custom payment processing.
Square gift cards can be used as a payment source. When your application uses the Payments API to process a gift card payment, Square automatically creates a REDEEM
activity to update the gift card balance and record the redemption. You don't need to call CreateGiftCardActivity
directly.
For the source_id
field in the CreatePayment request, you can specify either of the following:
A payment token - Used when buyers provide a gift card number (GAN) to make online payments with the Web Payments SDK or in-app payments with the In-App Payments SDK.
A gift card ID - Used for other payment scenarios, such as payments from a gift card on file.
If your application uses the Orders API to process orders, you can use the id
and location_id
from the order in your payment request.
When using the Web Payments SDK or In-App Payments SDK, the SDK generates a secure payment token from the GAN entered by the buyer. You then provide this payment token as the source_id
in your CreatePayment
request:
Create payment
You can optionally use the payment token generated by the SDK to call RetrieveGiftCardFromNonce to check the gift card balance and state before creating the payment or show the balance to the buyer after completing the payment.
For steps that show how to modify the Web Payments SDK quickstart project to generate a payment token for a gift card, see Take a Gift Card Payment. For steps that show how to redeem a gift card payment using a payment token, see Walkthrough 2: Use a Gift Card (option 2).
You can provide a gift card ID as the source_id
in a CreatePayment
request:
Create payment
Square supports several methods to get the gift card ID if needed. For example:
If you collect the GAN from the buyer, call RetrieveGiftCardFromGAN.
If you're making a payment from a gift card on file and you have the ID of the linked customer, call ListGiftCards with the
customer_id
query parameter. If you need to get the customer ID, call SearchCustomers.
Note
All CreatePayment
examples in this topic include the optional, but recommended, customer_id
field.
If provided in a payment request, the customer_id
field can specify the ID of any customer in the seller's Customer Directory. For more information, see Considerations.
For steps that show how to redeem a gift card payment from a gift card on file, see Walkthrough 2: Use a Gift Card (option 2).
If the CreatePayment
request is successful, Square returns a payment similar to the following example:
{
"payment": {
"id": "l8753iAyu16jip83wkGHTwEXAMPLE",
"created_at": "2021-09-10T00:11:48.384Z",
"updated_at": "2021-09-10T00:11:49.311Z",
"amount_money": {
"amount": 1350,
"currency": "USD"
},
"status": "COMPLETED",
"delay_duration": "PT168H",
"source_type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "SQUARE_GIFT_CARD",
"last_4": "2013",
"exp_month": 12,
"exp_year": 2099,
"fingerprint": "sq-1-axn6GGaDl7bZMS5LAPsvaiO63DehyOYFcyo-wAvBCGegIDgthtpC0u8eerS2hi8DWA",
"card_type": "DEBIT",
"prepaid_type": "PREPAID",
"bin": "778332"
},
"entry_method": "KEYED",
"auth_result_code": "0",
"card_payment_timeline": {
"authorized_at": "2021-09-10T00:11:48.443Z",
"captured_at": "2021-09-10T00:11:49.312Z"
}
},
"location_id": "LNCXKAEXAMPLE",
"order_id": "PVGawfEPg4I5BmPiNT5l8EXAMPLE",
"customer_id": "9HRM2DFVBH73GGXRW4DEXAMPLE",
"risk_evaluation": {
"created_at": "2021-09-10T00:11:48.959Z",
"risk_level": "NORMAL"
},
"total_money": {
"amount": 1350,
"currency": "USD"
},
"approved_money": {
"amount": 1350,
"currency": "USD"
},
"receipt_number": "l875",
"receipt_url": "https://squareup.com/receipt/preview/l8753iAyu16jip83wkGHTSCNCMTZY",
"delay_action": "CANCEL",
"delayed_until": "2021-09-17T00:11:48.384Z",
"version_token": "uv2Q6v5IZqCbUyVWo4TOFziAAzK383Wli9MzGMs2O5C6o"
}
}
A gift card payment has the following card_details.card
settings:
card_brand
isSQUARE_GIFT_CARD
.card_type
isDEBIT
.prepaid_type
isPREPAID
.
Neither the Web Payments SDK, In-App Payments SDK, nor CreatePayment
response exposes the gift card ID or full GAN.
If your application doesn't use the Payments API to process payments, you must create a REDEEM
activity to update the gift card balance after taking a gift card payment. To do so, call CreateGiftCardActivity and provide the following information for gift_card_activity
in the request:
gift_card_id
orgift_card_gan
- The gift card ID or GAN. Only one is required to create the activity.type
- SpecifyREDEEM
.redeem_activity_details
- Details about theREDEEM
activity:amount_money
- The amount to deduct from the gift card balance. In this example, the gift card was redeemed for a $3 purchase.reference_id
- An optional ID that associates the activity with an order or payment in your custom processing system.
location_id
- The location where the activity occurred. If needed, call ListLocations to get the location ID.
Create gift card activity
The CreateGiftCardActivity
response contains a GiftCardActivity object, as shown in the following example. The activity contains information about the gift card, including the updated balance.
{
"gift_card_activity": {
"id": "gcact_8705537d2d75461da6d681384115c401",
"type": "REDEEM",
"location_id": "S8GWD5R9QB376",
"created_at": "2021-04-11T20:44:32.000Z",
"gift_card_id": "gftc:01696eaf3d5141bfb4c7869494257bb6",
"gift_card_gan": "7783320005719034",
"gift_card_balance_money": {
"amount": 2200,
"currency": "USD"
},
"redeem_activity_details": {
"amount_money": {
"amount": 300,
"currency": "USD"
},
"reference_id": "client-side-example-reference-id",
"status": "COMPLETED"
}
}
}
For steps that show how to redeem a gift card payment when using custom payment processing, see Redeem and Reload a Gift Card When Using a Custom Processing System.
If your application uses the Orders API to process orders and the Payments API to process payments, your payment request can use partial authorization with delayed capture to automatically process a partial gift card payment for an order.
To configure CreatePayment
to accept a partial gift card payment:
- Set
accept_partial_authorization
totrue
. - Set
autocomplete
tofalse
. - Set
amount_money
to thetotal_money
amount for the order. If the gift card balance is insufficient to pay this amount, Square creates a payment equal to the gift card balance.
Create payment
If another payment is needed, set amount_money
in your payment request to the outstanding order amount (the total order amount any minus collected payments).
- For another gift card payment, set
accept_partial_authorization
totrue
andautocomplete
tofalse
. - For other payment types, omit
accept_partial_authorization
and setautocomplete
tofalse
.
When the total order amount is collected, call PayOrder
to complete the order. For more information, see Partial Payment Authorizations, Delayed Capture, and Walkthrough: Partial Payments with Gift Cards.
Note that partial authorization doesn't support tips. A CreatePayment
request that includes tip_money
and sets accept_partial_authorization
to true
is successful only if the gift card balance is sufficient to pay the order amount and tip amount combined. Otherwise, Square returns an INSUFFICIENT_FUNDS
error.
In the Sandbox, you can create gift card payments by calling CreatePayment and providing one of the following values for the required source_id
:
Test payment token - Square provides test payment tokens that you can use to test gift card payments:
- To test a successful payment, use
cnon:gift-card-nonce-ok
. - To test a failed payment, use
cnon:gift-card-nonce-insufficient-funds
orcnon:gift-card-nonce-insufficient-permission
.
Using a test payment token skips the step of generating the token with the Web Payments SDK or In-App Payments SDK.
The following example uses
cnon:gift-card-nonce-ok
as thesource_id
:Create payment
Although Square-provided test values can successfully complete a payment in the Sandbox, they aren't tied to any gift cards. Therefore, Square doesn't create a gift card activity to update the gift card balance or send related webhook notifications.
- To test a successful payment, use
Payment token generated for the test GAN - You can use the test GAN provided by Square (
7783 3200 0000 0000
) to generate a token using the Web Payments SDK or In-App Payments SDK. Each payment token is valid for a single payment. Note that the Web Payments SDK and In-App Payments SDK don't accept the GANs of any gift cards that you create.The following example uses a generated payment token as the
source_id
:Create payment
Although payments originating from the test GAN always succeed, they aren't tied to any gift cards. Therefore:
- Square doesn't create a gift card activity to update the gift card balance or send related webhook notifications.
- Payment tokens generated using the test GAN cannot be used with the
RetrieveGiftCardFromNonce
endpoint to retrieve a gift card.
Gift card ID - You can use the ID of a gift card created and activated in your Sandbox environment. After the payment is completed, Square creates the
REDEEM
gift card activity that updates the gift card balance. You can use this method to test with different gift card balances and states.The following example uses a gift card ID as the
source_id
:Create payment
The receipt_url
of a Sandbox payment isn't a working URL. Square doesn't host receipts for Sandbox payments.
The following considerations apply to redeeming gift cards:
You can retrieve the gift card if you want to check the gift card balance and state before creating the payment or show the balance to the buyer after completing the payment.
Square allows you to configure your payment requests to automatically process partial gift card payments for a payment.
Unlike using a credit or debit card ID, the
customer_id
field is optional for payments made using a gift card ID. If provided,customer_id
can specify the ID of any customer in the seller's Customer Directory; Square doesn't validate that the specified customer is linked to the gift card. As a best practice, you should provide acustomer_id
in yourCreatePayment
requests.REDEEM
activities are returned in ListGiftCardActivities results. Use thetype
query parameter to filter for allREDEEM
activities in the seller's Square account.Square invokes the
gift_card.updated
andgift_card.activity.created
webhook events after aREDEEM
activity is created, as well aspayment.created
,payment.updated
, andorder.updated
when your application uses the Orders API and Payments API.Square also invokes
order.created
if the payment request doesn't specify an order ID andgift_card.activity.updated
if the payment transitions from thePENDING
toCOMPLETED
state.