In this scenario, an online payment-processing application creates multiple online payments for an order. These payment amounts add up to the total amount to be charged for the itemized order.
The application uses a payment form that accepts card payments and reads from an Order object that represents the total amount of the payment. With the Web Payments SDK, each card payment (credit card and gift card) generates a payment token that represents the payment and the value entered for each split payment. The application uses the Payments API to manage the split payment processing by creating a Payment object, which represents each payment request.
For gift cards and card payments that represent a split payment transaction, Square authorizes the payments for the specified amount. The application then receives the returned Payment object and compares the payment value with the total payment amount from the order. If the buyer needs to make subsequent split payments to complete the order, the application notifies the buyer in the frontend and repeats the payment processing flow until the application completes the order with all of the payments processed.
Link to section
What you'll learn
By the end of this scenario, you'll know:
How to accept multiple payment sources for an online order.
How to incorporate a client-side SDK for taking payments and multiple Square APIs to process split payments.
How to use Square developer tools to gain expertise on the Square Developer platform while using Square APIs.
You have a personal access token. While not part of this scenario, note that applications that use OAuth require an OAuth access token that grants PAYMENTS_WRITE, ORDERS_READ, and ORDERS_WRITE permissions.
You have an order that was previously created using the Orders API. Integration with the Orders API is required to link multiple payments to a single order.
You've set up the Web Payments SDK for your application frontend to generate a payment token for multiple payments.
An activated gift card with a balance of $25 or more.
To accept multiple payments, the payment method form should include a field for entering credit card information. The frontend application performs the following steps after the buyer submits a card number:
Generates the payment token using the Web Payments SDK.
Sends the payment token, payment method, and order information, which includes the payment amounts calculated for the total amount of the order. The payment token is used as the source_id in CreatePayment requests.
To get the total amount due for the order, call RetrieveOrder in the Orders API and check the total_money field.
Make the CreatePayment request to the Payments API using information sent from the frontend and the order amount. If the first payment request is for a gift card, the payment is configured to use delayed capture and partial authorization, as well as the following values:
accept_partial_authorization is true.
autocomplete is false.
amount_money.amount is the total order amount.
These settings direct Square to authorize a payment up to the specified amount. If the gift card doesn't have a sufficient balance, Square authorizes a payment amount equal to the gift card balance. For this scenario, assume that the order amount is $25 and the gift card has a $10 balance.
Create payment
Important
If you're testing this step in the Square Sandbox without generating a payment token from the Web Payments SDK, you can provide the id of the gift card that has an insufficient balance. The Sandbox gift card values don't work for this split payment scenario.
After receiving the request, Square does the following:
Gift card - Creates a REDEEM activity with status set to PENDING, sets the gift card balance to 0, and reserves the $10 that was removed from the balance until the payment is completed or canceled.
Order - Adds payment information to the tenders field of the order.
Payment - Creates a $10 payment with status set to APPROVED and card_details.status set to AUTHORIZED.
Webhooks - Invokes the gift_card.updated, gift_card.activity.created, order.updated, and payment.created events.
Square also returns the new Payment object in the response. The backend compares the amount_money in the payment with the total order amount to determine whether another payment is needed. For this scenario, the backend notifies the frontend that an additional payment of $15 is needed.
To get the total amount of authorized payments for the order, call RetrieveOrder in the Orders API. In the tenders field, check the amount_money field of each AUTHORIZED payment.
Checkpoint - Is amount_money combined for all authorized payments equal to the total order amount?
Yes - Call PayOrder to complete the order.
No - Notify the frontend to collect another payment.
Repeat the process of setting up the payment form, receiving the payment token from the Web Payments SDK, and passing the token to the backend (as described in step 1). The second payment can be any type of payment that the Web Payments SDK supports, but for this scenario, assume the buyer provides credit card information.
Build and send additional CreatePayment requests with the Payments API using information collected from the application and calculating the remaining order amount.
In this scenario, the second payment is made using a credit card, so the payment is configured to use delayed capture but not partial authorization:
autocomplete is false
amount_money.amount is the remaining amount due
Create payment
After receiving the request, Square does the following:
Order - Adds payment information to the tenders field of the order.
Payment - Creates a $15 payment with status set to APPROVED and card_details.status set to AUTHORIZED.
Webhooks - Invokes the order.updated and payment.created events.
Square also returns the new Payment object in the response. The backend compares the amount_money in the payment with the total order amount and determines that the order is fully paid.
To retrieve the remaining balance for the order, call RetrieveOrder in the Orders API. In the tenders field, check the amount_money field of each AUTHORIZED payment.
Call PayOrder to complete the order.
Send a PayOrder request to the Orders API and provide the payment IDs.
Pay order
After receiving the request, Square does the following:
Gift card - Updates the REDEEM activity with status set to COMPLETED and permanently removes the reserved funds.
Order - Updates payment-related fields on the order and changes status to COMPLETED.
Payment - Creates a $10 payment with status set to APPROVED and card_details.status set to AUTHORIZED.
Webhooks - Invokes the gift_card.updated, gift_card.activity.updated, order.updated, and payment.updated events.
Square also returns the updated Order object in the response. The backend notifies the frontend that the order is fully paid.
Display the completed order status to the buyer in your application. Provide the order confirmation detailing each of the completed payments and include any additional charges such as tips and taxes if needed.
Link to section
Next steps
After learning how an application uses Payments, Orders, OAuth, and Customers APIs to process multiple payments, explore each API's full capability by reading the following topics: