Learn how partial payments work when a gift card is a payment source in a CreatePayment request.
Payments API

Partial Payment Authorizations

A partial payment authorization allows the Payments API to support Square Gift Cards. It lets a buyer use the full balance of their Square Gift Card to make a partial payment on an order even when the balance is not sufficient. The gift card payment is completed when the buyer presents an additional payment method to cover the balance of the order and the order is paid.

Note

An authorized gift card payment reserves the payment amount in the Square Gift Card balance until the associated Order is paid. At that point, the funds are subtracted from the gift card balance. Reserved gift card funds cannot be used for another order.

By default, CreatePayment returns an error when the specified payment source does not have a sufficient balance to pay the amount specified in the request. Applications can use the optional accept_partial_authorization parameter to take partial payments. Partial payments can only be authorized. That is, the request must also set the autocomplete parameter to false in the request body. An authorized gift card payment is completed by calling the Orders API PayOrder endpoint with the Order ID of the order that includes the gift card payment ID.

Note that some card networks might not support partial payments and applications should handle errors accordingly.

A typical scenario is a buyer chooses to make multiple payments for an order. The buyer uses a gift card balance to partially pay for an order. The buyer then makes additional payments to pay for the remaining order amount.

For example, the following CreatePayment request attempts to charge $20 to a Square gift card on file. The request specifies a gift card ID on file.

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
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 '{
    "idempotency_key": "{UNIQUE_KEY}",
    "autocomplete": true,
    "amount_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "source_id": "{GIFT_CARD_ON_FILE_ID}"
  }'

If the Square gift card does not have sufficient funds, the request returns an error. An example error response is shown:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
{
   "errors":[
      {
         "code":"INSUFFICIENT_FUNDS",
         "detail":"Authorization error: 'INSUFFICIENT_FUNDS'",
         "category":"PAYMENT_METHOD_ERROR"
      }
   ],
   "payment":{
      ...
      },
      "status":"FAILED",
      "source_type":"CARD",
      "card_details":{
         "status":"FAILED",
         ...
         "errors":[
            {
               "code":"INSUFFICIENT_FUNDS",
               "detail":"Authorization error: 'INSUFFICIENT_FUNDS'",
               "category":"PAYMENT_METHOD_ERROR"
            }
         ]
      }
   }
}

You can include the optional accept_partial_authorization parameter in the request body to allow taking partial payments. You must also set the autocomplete parameter to false to obtain only payment authorization.

In the preceding example, the CreatePayment request attempts to charge $20. Suppose the Square gift card specified in the request has only $10 available. If you allow accepting a partial payment, the request is approved for $10 as shown:

The buyer can then use other payment sources to pay for the order. After the buyer pays for the order, the application can complete the authorized multiple payments using the Orders API. For more information, see Orders integration.

Important

It is the responsibility of the application developer to compare amount_money in the response with amount_money specified in the request. If the amount is less, the application should prompt the buyer for an additional payment to cover the remainder or cancel the gift card payment.

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