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

Take Partial Payments

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.

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