Walkthrough: Partial Payments with Gift Cards

Learn how to add and manage Square gift card payments with an existing Web Payments SDK integration, Gift Cards API, Orders API, and Payments API for your application.

This topic assumes that you're familiar with these APIs and the Web Payments SDK.

This walkthrough covers the following tasks:

• Using the Orders API to create an order and to complete the order.
• Using the Payments API to create the Payment objects and process gift card payments with the payment token.

The following sections cover an end-to-end payment processing flow for a partial payment. You process a $30 payment using a gift card worth $5 and complete the remaining balance of $25 using a credit card.

Before starting, make sure that you've created the following:

• A payment form that you created with the Web Payments SDK that accepts gift card payments.
• An activated gift card worth $5 USD, created with the Gift Cards API.

1. Create a new Order object for a purchase worth $30 USD.

   Create order

   cURL

   The response object returns the new order.

   {
      "order": {
        "id": "F7iOm8FdcIkIfnJS28Pzcym1Ue4F",
        "location_id": "LMGQR286E3GKP",
        "line_items": [
          {
            "uid": "s4OlFe3qRquyNqipYUqiAC",
            "quantity": "1",
            "name": "30 dollar item",
            "base_price_money": {
              "amount": 3000,
              "currency": "USD"
            },
            "gross_sales_money": {
              "amount": 3000,
              "currency": "USD"
            },
            "total_tax_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_discount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_money": {
              "amount": 3000,
              "currency": "USD"
            },
            "variation_total_price_money": {
              "amount": 3000,
              "currency": "USD"
            },
            "item_type": "ITEM"
          }
        ],
        "created_at": "2023-06-21T23:18:06.591Z",
        "updated_at": "2023-06-21T23:18:06.591Z",
        "state": "OPEN",
        "version": 1,
        "total_tax_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_tip_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_money": {
          "amount": 3000,
          "currency": "USD"
        },
        "total_service_charge_money": {
          "amount": 0,
          "currency": "USD"
        },
        "net_amounts": {
          "total_money": {
            "amount": 3000,
            "currency": "USD"
          },
          "tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "discount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "tip_money": {
            "amount": 0,
            "currency": "USD"
          },
          "service_charge_money": {
            "amount": 0,
            "currency": "USD"
          }
        },
        "source": {
          "name": "Sandbox for sq0idp-Uszzj3sFOClCC73EQlvXfA"
        }
      }
    }

When you create the payments, include the order ID and location ID from the Order object in the payment requests.

Create the first payment. Set accept_partial_authorization to true and autocomplete to false so that you can create a partial payment transaction from the gift card. If the gift card has insufficient funds to pay the total order amount, Square creates a payment for the amount of the gift card balance.

1. Create the first payment.

   Create payment

   cURL

   The CreatePayment endpoint returns the Payment object for the amount that was paid from the gift card.

   {
      "payment": {
        "id": "b3Bsljedae2tB4jbl7R5EWYJ2oMZY",
        "created_at": "2023-06-21T23:19:44.531Z",
        "updated_at": "2023-06-21T23:19:44.569Z",
        "amount_money": {
          "amount": 500,
          "currency": "USD"
        },
        "status": "APPROVED",
        "delay_duration": "PT168H",
        "source_type": "CARD",
        "card_details": {
          "status": "AUTHORIZED",
          "card": {
            "card_brand": "SQUARE_GIFT_CARD",
            "last_4": "0000",
            "exp_month": 12,
            "exp_year": 2050,
            "fingerprint": "sq-1-y_yFcziMlsxVSomRNQZ7xBaW0F1xxE-6TbcGKl7KOoy3GI1mh094CY4_Ox5RzUN7Vg",
            "card_type": "DEBIT",
            "prepaid_type": "PREPAID",
            "bin": "778332"
          },
          "entry_method": "KEYED",
          "auth_result_code": "0",
          "card_payment_timeline": {
            "authorized_at": "2023-07-25T17:54:52.927Z"
          }
        },
        "location_id": "LMGQR286E3GKP",
        "order_id": "F7iOm8FdcIkIfnJS28Pzcym1Ue4F",
        "total_money": {
          "amount": 500,
          "currency": "USD"
        },
        "approved_money": {
          "amount": 500,
          "currency": "USD"
        },
        "capabilities": [
          "EDIT_AMOUNT_UP",
          "EDIT_AMOUNT_DOWN",
          "EDIT_TIP_AMOUNT_UP",
          "EDIT_TIP_AMOUNT_DOWN"
        ],
        "receipt_number": "b3Bs",
        "delay_action": "CANCEL",
        "delayed_until": "2022-06-28T23:19:44.531Z",
        "application_details": {
          "square_product": "ECOMMERCE_API",
          "application_id": "sandbox-sq0idb-Zlu34ljDn3fSaDM2_ut4nA"
        },
        "version_token": "MDkCzT8c6qcJhLjhfvKmJO3EndoXWdKBf4X5XvKYVpo6o"
      }
    }

2. Create the additional payment request for the remaining order amount. Set autocomplete to false, so you can create a partial payment transaction from the credit card. The accept_partial_authorization field doesn't apply to credit card payments and defaults to false, so you can omit it from the request.

   Create payment

   cURL

   The CreatePayment endpoint returns the additional Payment object.

   {
      "payment": {
        "id": "ewoifnDF77456cw45351u5D5hgd90",
        "created_at": "2023-06-21T23:19:44.531Z",
        "updated_at": "2023-06-21T23:19:44.569Z",
        "amount_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "status": "APPROVED",
        "delay_duration": "PT168H",
        "source_type": "CARD",
        "card_details": {
          "status": "AUTHORIZED",
          "card": {
            "card_brand": "VISA",
            "last_4": "0000",
            "exp_month": 12,
            "exp_year": 2050,
            "fingerprint": "sq-1-q-JDrVQasjkputIAhtJYyZp36HZupBuNw4iTEZyKH3riC0nvigE1qJcJkFSCKBEQqA",
            "card_type": "CREDIT",
            "prepaid_type": "NOT_PREPAID",
            "bin": "778332"
          },
          "entry_method": "KEYED",
          "auth_result_code": "0",
          "card_payment_timeline": {
            "authorized_at": "2022-06-21T23:19:44.569Z"
          }
        },
        "location_id": "LMGQR286E3GKP",
        "order_id": "F7iOm8FdcIkIfnJS28Pzcym1Ue4F",
        "total_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "approved_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "capabilities": [
          "EDIT_AMOUNT_UP",
          "EDIT_AMOUNT_DOWN",
          "EDIT_TIP_AMOUNT_UP",
          "EDIT_TIP_AMOUNT_DOWN"
        ],
        "receipt_number": "b3Bs",
        "delay_action": "CANCEL",
        "delayed_until": "2022-06-28T23:19:44.531Z",
        "application_details": {
          "square_product": "ECOMMERCE_API",
          "application_id": "sandbox-sq0idb-Zlu34ljDn3fSaDM2_ut4nA"
        },
        "version_token": "MDkCzT8c6qcJhLjhfvKmJO3EndoXWdKBf4X5XvKYVpo6o"
      }
    }

   For more information about creating payment objects for partial payments, see Partial Payment Authorizations.

Use the PayOrder endpoint of the Orders API and include the order_id of the authorized order in the PayOrder endpoint's path parameter.

The following PayOrder request object uses b3Bsljedae2tB4jbl7R5EWYJ2oMZY and ewoifnDF77456cw45351u5D5hgd90 from the first and second Payment response objects, respectively, from the walkthrough: