Take Partial Payments with Square Gift Cards

Applies to: Web Payments SDK | Gift Cards API | Payments API | Orders API

Learn how to process partial payments with Square Gift Cards, the Web Payments SDK, and other APIs.

You can 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.

You will learn about:

• Using the OAuth API to create and complete an 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 with a $5 balance and complete the remaining $25 balance using a credit card.

• A payment form that you created with the Web Payments SDK that accepts gift card payments.
• An activated gift card with a $5 balance, created with the Gift Cards API.
• You're familiar with these APIs and the Web Payments SDK.

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: