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 isn't 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.

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 doesn't 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 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.

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

{
   "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.

"accept_partial_authorization" : true,
"autocomplete" : false

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:

{
   "payment":{
         ...
         "amount":1000,
         "currency":"USD"
      },
      "status":"APPROVED",
      "source_type":"CARD",
      "card_details":{
         "status":"AUTHORIZED",
         "card":{
            "card_brand":"SQUARE_GIFT_CARD",
            ...
         },
         ...
      }
   }
}

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.

• Delayed Capture of a Card Payment
• Card Payments