Learn how to redeem and reload a Square gift card using the Gift Card Activities API.
Gift Cards API

Walkthrough 2: Use a Gift Card Beta release
This is pre-release documentation for an API in public beta and is subject to change.

This walkthrough assumes that you completed Walkthrough 1: Sell a Gift Card and activated a gift card. In this walkthrough, you redeem the gift card for a purchase, load additional funds on the gift card, and list the activity history for the gift card.

Step 1: Redeem the gift card for a purchase Permalink Get a link to this section

Buyers can use an activated gift card to pay for a purchase. The redemption workflow depends on whether your application processes payments using the Payments API.

Using the Payments API Permalink Get a link to this section

The following procedure assumes that your application uses the Payments API to process payments. First, you create an order and take the gift card payment for the order. After the transaction is completed, Square automatically updates the gift card balance.

  1. Call CreateOrder to create an order.

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    curl https://connect.squareupsandbox.com/v2/orders \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "{LOCATION_ID}",
          "line_items": [
            {
              "name": "Stadium backpack",
              "quantity": "1",
              "base_price_money": {
                "amount": 1599,
                "currency": "USD"
              }
            }
          ]
        }
      }'
  2. Copy the id of the order from the response. You use this value when you create a payment.

  3. Generate a secure payment token for the gift card using the Web Payments SDK or In-App Payments SDK.

    Note

    For this walkthrough, you skip this step and use a test payment token for your CreatePayment request in the next step. The test payment token cannot be used to retrieve a gift card, so you also skip the step of calling RetrieveGiftCardFromNonce to get the gift card balance and state before creating the payment.

  4. Call CreatePayment to pay for the order using the payment token. In the request, the cnon:gift-card-nonce-ok value specified for source_id is the test payment token for a Sandbox gift card.

    Create Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    curl https://connect.squareupsandbox.com/v2/payments \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "source_id": "cnon:gift-card-nonce-ok",
        "idempotency_key": "{UNIQUE_KEY}",
        "amount_money": {
          "amount": 1599,
          "currency": "USD"
        },
        "order_id": "{ORDER_ID}",
        "location_id": "{LOCATION_ID}"
      }'

    The response should show that the payment status is COMPLETED and the card_details status is CAPTURED.

    When you use the Payments API to process the payment, Square automatically creates a REDEEM activity that updates the gift card balance after the transaction is successfully completed.

    You should be aware of the following considerations for gift card payments:

    • Square supports taking partial payments with Square gift cards.

    • In the production environment, the CreatePayment endpoint also accepts a gift card ID as the source_id. However, the Sandbox environment does not currently support using a gift card ID for a payment.

    • When using a payment token for a gift card payment, you can use the RetrieveGiftCardFromNonce endpoint to retrieve the gift card. Neither the Web Payments SDK, In-App Payments SDK, nor CreatePayment response expose the gift card ID or full GAN.

  5. Optional. Retrieve the gift card and get the updated balance to display to the buyer.

    Note

    For this walkthrough, you skip this step. The test payment token used for the CreatePayment request is not associated with your gift card, so the balance was not updated.

  6. Continue to Step 2: Add money to the gift card.

Using non-Square APIs Permalink Get a link to this section

The following procedure assumes that your application uses a custom payment processing system. To update the gift card balance after the transaction is completed, you must call CreateGiftCardActivity in the Gift Card Activities API and create a REDEEM activity.

  1. Use your custom processing system to create and take payment for the order. For this walkthrough, assume that you processed a $3 gift card payment from the buyer.

    During this process, you can check the gift card balance and state by calling RetrieveGiftCardFromGAN using the gift card account number (GAN) that you collected from the buyer.

  2. Call CreateGiftCardActivity to update the gift card balance. This endpoint supports various activity types, so you must specify the REDEEM activity type and provide related details in the redeem_activity_details field.

    • For gift_card_gan, provide the GAN that you collected from the buyer. For this walkthrough, you can use the GAN of any activated gift card.

    • 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.

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_gan": "{GIFT_CARD_ACCOUNT_NUMBER}",
          "type": "REDEEM",
          "location_id": "{LOCATION_ID}",
          "redeem_activity_details": {
            "amount_money": {
              "amount": 300,
              "currency": "USD"
            },
            "reference_id": "line-item-id"
          }
        }
      }'

    Note

    You can provide the gift_card_id or gift_card_gan in your CreateGiftCardActivity requests.

    The following example response shows the updated gift card balance and the amount that was redeemed:

  3. Optional. Show the updated balance to the buyer.

Step 2: Add money to the gift card Permalink Get a link to this section

In 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 activated gift cards.

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 information you provide in the request depends on whether your application processes orders and payments using the Orders API and Payments API.

Using the Orders API and Payments API Permalink Get a link to this section

The following procedure assumes that your application uses the Orders API and Payments API to process orders and payments. First, you create an order and take payment for the order. After the transaction is completed, you create a LOAD activity and provide the order and line item IDs.

  1. Call CreateOrder to create an order for the amount to add to the gift card. In the order, the line item for the gift card funds must specify an item_type of GIFT_CARD. Otherwise, the order is not processed as a gift card order and the corresponding LOAD activity does not succeed.

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    curl https://connect.squareupsandbox.com/v2/orders \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "{LOCATION_ID}",
          "line_items": [
            {
              "name": "Reload Gift Card via API",
              "quantity": "1",
              "item_type": "GIFT_CARD",
              "base_price_money": {
                "amount": 1000,
                "currency": "USD"
              }
            }
          ]
        }
      }'
  2. 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 load the gift card.

    • You provide the UID of the GIFT_CARD line item when you load the gift card.

  3. 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 your CreatePayment request in the next step.

  4. Call CreatePayment to pay for the order. In the request, the cnon:card-nonce-ok value specified for source_id is the test payment token for a Sandbox credit card.

    Create Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    curl https://connect.squareupsandbox.com/v2/payments \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "source_id": "cnon:card-nonce-ok",
        "idempotency_key": "{UNIQUE_KEY}",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "order_id": "{ORDER_ID}",
        "location_id": "{LOCATION_ID}"
      }'

    The response should show that the payment status is COMPLETED and the card_details status is CAPTURED. Because the order is now fully paid, Square sets the order state to COMPLETED.

    Note that the CreatePayment response does not include the gift card ID or full GAN.

  5. Call CreateGiftCardActivity to load the money on the gift card. This endpoint supports various activity types, so you must specify the LOAD activity type and provide related details in the load_activity_details field.

    • For gift_card_gan, provide the GAN that you collected from the buyer or previously retrieved. For this walkthrough, you can use the GAN of any activated gift card.

    • For order_id, specify the ID of the associated order. The order state must be COMPLETED.

    • 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.

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_gan": "{GIFT_CARD_ACCOUNT_NUMBER}",
          "type": "LOAD",
          "location_id": "{LOCATION_ID}",
          "load_activity_details": {
            "order_id": "{ORDER_ID}",
            "line_item_uid": "{LINE_ITEM_UID}"
          }
        }
      }'

    Note

    You can optionally use gift_card_id to load a gift card instead of gift_card_gan.

    The following example response shows the updated gift card balance and the amount that was added:

  6. Optional. Show the updated balance to the buyer.

  7. Continue to Step 3: List gift card activities.

Using non-Square APIs Permalink Get a link to this section

The following procedure assumes that your application uses a custom system to process orders and payments. After the transaction is completed, you create a LOAD activity and provide the amount to load, any payment instrument IDs, and an optional reference ID.

  1. Using your custom processing system, process the payment for the amount the buyer wants to add to the gift card. For this walkthrough, assume that you processed a $10 payment from the buyer.

  2. Call CreateGiftCardActivity to load the money on the gift card. This endpoint supports various activity types, so you must specify the LOAD activity type and provide related details in the load_activity_details field.

    • For gift_card_gan, provide the GAN that you collected from the buyer. For this walkthrough, you can use the GAN of any activated gift card.

    • 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.

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2022-05-12' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_gan": "{GIFT_CARD_ACCOUNT_NUMBER}",
          "type": "LOAD",
          "location_id": "{LOCATION_ID}",
          "load_activity_details": {
            "amount_money": {
              "amount": 1000,
              "currency": "USD"
            },
            "buyer_payment_instrument_ids": [
              "card-id"
            ],
            "reference_id": "line-item-id"
          }
        }
      }'

    Note

    You can provide the gift_card_id or gift_card_gan in your CreateGiftCardActivity request.

    The following example response shows the updated gift card balance and the amount that was added:

  3. Optional. Show the updated balance to the buyer.

Step 3: List gift card activities Permalink Get a link to this section

To see the activity history for a gift card, call ListGiftCardActivities using the giftcard_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
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/gift-cards/activities?gift_card_id={{gift_card_id}} \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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 are testing this walkthrough in the Sandbox, you can review gift card activities in the Sandbox Seller Dashboard.

  1. Open the Developer Dashboard.

  2. 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.

  3. In the navigation pane, choose Gift Cards.

  4. 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.

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.