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.

Link to section

Overview

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

Link to section

Requirements and limitations

Link to section

1. Create the order for the item transaction

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

    Create order

    The response object returns the new order.

Link to section

2. Create the payment requests for the partial payment order

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

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

  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

    The CreatePayment endpoint returns the additional Payment object.

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

Link to section

3. Create and complete the partial payment

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:

Pay order