Process a gift card order using the Orders API and take payment using the Payments API. You can create and activate a gift card using the Gift Cards API.
Gift Cards API: Walkthrough 1

Create and Activate a Gift Card When Using Orders API Integration

This walkthrough shows how to sell a Square gift card when your application uses the Orders API and Payments API to process orders and payments. First, you take an order for a gift card using the Orders API and pay for the order using the Payments API. Then, you create a gift card and activate it with an initial balance. After the gift card is activated, it is ready for use.

Did you know?

Watch the Sandbox 101: Gift Cards API video to see how to purchase, create, and activate a gift card using steps that are similar to this walkthrough. You can also check out the Gift Cards API Sample App and the accompanying Gift Cards API Sample App Overview video to see how you can create and manage gift cards in a Node.js application.

To enable a buyer to purchase a gift card for themselves or another recipient, you create a gift card order using the Orders API and take payment for the order using the Payments API.

Note

To learn how to create and activate a gift card when your application uses a custom order and payment processing system, see Create and Activate a Gift Card When Using a Custom Processing System.

  1. Call CreateOrder to create an order for a gift card. In the request, the line item for the gift card must specify an item_type of GIFT_CARD. Otherwise, the order is not processed as a gift card sale and the subsequent gift card activation 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-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "{LOCATION_ID}",
          "line_items": [
            {
              "name": "eGiftCard via API",
              "quantity": "1",
              "item_type": "GIFT_CARD",
              "base_price_money": {
                "amount": 2500,
                "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 activate the gift card.

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

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

  2. Call CreatePayment to take the payment for the order.

    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-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "source_id": "cnon:card-nonce-ok",
        "idempotency_key": "{UNIQUE_KEY}",
        "amount_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "order_id": "{ORDER_ID}",
        "location_id": "{LOCATION_ID}"
      }'

    In the response, the payment status is set to COMPLETED. Because the order is fully paid, Square also sets the order state to COMPLETED.

At this point, the gift card is reported as pending activation in the Seller Dashboard. Because you are using the Sandbox for testing, you can view the reports in the Seller Dashboard associated with your Sandbox test account.

  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. Choose Reports.

  4. Choose Gift Cards and verify that the report shows the pending activation.

After the buyer pays for the gift card order, you create a gift card using the Gift Cards API and activate the gift card with an initial balance using the Gift Card Activities API.

  1. Call CreateGiftCard to create a digital gift card.

    Create Gift Card
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    curl https://connect.squareupsandbox.com/v2/gift-cards \
      -X POST \
      -H 'Square-Version: 2022-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "location_id": "{LOCATION_ID}",
        "gift_card": {
          "type": "DIGITAL"
        }
      }'

    The previous request specifies only the gift card type, which directs Square to generate the gift card account number (GAN). However, providing a custom GAN is also supported.

    Note

    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.

    The following example response shows the gift card state is PENDING and the current balance is 0:

  2. Copy the id from the response. You use this value to activate the gift card.

  1. Call CreateGiftCardActivity to activate the gift card with an initial balance. The request must include either gift_card_id with the gift card ID or gift_card_gan with the GAN.

    This endpoint supports various activity types. For an ACTIVATE activity, you provide activity-specific details in the activate_activity_details field:

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

    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-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_id": "{GIFT_CARD_ID}",
          "type": "ACTIVATE",
          "location_id": "{LOCATION_ID}",
          "activate_activity_details": {
            "order_id": "{ORDER_ID}",
            "line_item_uid": "{LINE_ITEM_UID}"
          }
        }
      }'

    The following is an example response:

  2. Optional. Call RetrieveGiftCard to see that the gift card state is set to ACTIVE and the balance is $25.

    Retrieve Gift Card
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/gift-cards/{id} \
      -H 'Square-Version: 2022-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    The following is an example response:

Now that the gift card is activated, you can open the Gift Cards reports page in the Sandbox Seller Dashboard and verify that the activity and gift card amount are listed under Activations. In addition, the gift card is now listed on the Overview page in the Gift Cards section of the Sandbox Seller Dashboard.

Buyers can purchase a gift card for themselves or for another recipient. The Gift Cards API does not provide email support, so your application must handle the delivery of the gift card information. For example, your application might choose to:

  • Show gift card information on the application website.

  • Email gift card information to the recipient.

Continue to Walkthrough 2: Use a Gift Card and learn how to pay for an order using an activated gift card.

In addition, you can explore the Gift Cards and Gift Card Activities APIs in other ways. For example, you can try out the Gift Cards sample (Node.js) or build and send API requests from API Explorer using your Sandbox access token.

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