Redeem Square Gift Cards

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 a REDEEM 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:

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:

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.

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 is SQUARE_GIFT_CARD.
• card_type is DEBIT.
• prepaid_type is PREPAID.

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 or gift_card_gan - The gift card ID or GAN. Only one is required to create the activity.

• type - Specify REDEEM.

• redeem_activity_details - Details about the REDEEM 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.

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 to true.
• Set autocomplete to false.
• Set amount_money to the total_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.

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 to true and autocomplete to false.
• For other payment types, omit accept_partial_authorization and set autocomplete to false.

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 or cnon: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 the source_id:

  Create payment

  cURL

  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.

• 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

  cURL

  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

  cURL

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 a customer_id in your CreatePayment requests.

• REDEEM activities are returned in ListGiftCardActivities results. Use the type query parameter to filter for all REDEEM activities in the seller's Square account.

• Square invokes the gift_card.updated and gift_card.activity.created webhook events after a REDEEM activity is created, as well as payment.created, payment.updated, and order.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 and gift_card.activity.updated if the payment transitions from the PENDING to COMPLETED state.

• Gift Cards API and Gift Card Activities API Overview
• Sample Application: Gift Card API Sample App
• Video: Gift Card API Sample App Overview
• Walkthrough 2: Use a Gift Card
• API Reference: Gift Cards
• API Reference: Gift Card Activities