Additional Payments API Considerations

Learn more about the Payments API, including payment status, payment minimums, payment integration with the Orders API, and viewing payments.

Payment status

When you take a payment using CreatePayment, you get a Payment object in the response, which includes the status field. The status field can be APPROVED, COMPLETED, CANCELED, or FAILED.

If Square is unable to get the requested funds, the status field is set to FAILED. Otherwise, status is set as follows:

• If the CreatePayment request specifies autocomplete to true, the payment is processed immediately and the resulting Payment object has status set to COMPLETED.

• If the CreatePayment request specifies autocomplete to false (requesting only payment authorization), the resulting Payment object has status set to APPROVED. You then have the following options:

  • Complete (or capture) the payment by calling CompletePayment. This changes the status value to COMPLETED.

  • Cancel the payment by calling CancelPayment. This changes the status value to CANCELED.

In terms of the seller receiving funds, the status values indicate the following:

• APPROVED:

  • For card payments, it indicates that the card is valid and the amount has been authorized by the cardholder's bank. The funds are guaranteed and the seller receives funds if the status value changes to COMPLETED (see CompletePayment).

  • For cash or external payments, this status has no impact because Square is not involved in any fund movement (the seller already has the funds).

• COMPLETED:

  • For card payments, the process to capture the funds with the cardholder's bank has initiated. The funds are guaranteed and the seller receives the funds.

  • For cash or external payments, this status has no impact because Square is not involved in any fund movement (the seller already has the funds).

• FAILED. The payment request was declined. The seller does not receive any funds.

• CANCELED. The card payment is voided and the funds are released. The seller does not receive any funds.

Payment minimums

For more information, see Monetary amount limits.

Optimistic concurrency

By default, any updates you apply to a Payment are applied in a last-write-wins manner, meaning newer updates overwrite older updates. For many applications, this behavior is sufficient. However, in a complex scenario (for example, you have multiple applications editing the same payment), Square supports optimistic concurrency for payment operations.

Each Payment includes a version_token field that uniquely identifies a specific version of the payment. You can optionally include this version_token in payment operations such as UpdatePayment, CompletePayment, and RefundPayment. In this case, the request succeeds only if the payment has not been updated since that version_token was generated.

Payments and locations

Every seller has a default location. The Payments API assumes the default location when you do not provide a location ID in a request. For example:

• In a CreatePayment request, if a location ID is not provided, Square assumes the default location of the seller. In a third-party application scenario, it is the default location of the seller for whom the application is taking the payment.

• In a ListPayment request, if a location ID is not provided, the endpoint returns a list of payments taken at the default location.

To find your default location name when taking a payment on behalf of yourself:

Orders integration

The following considerations apply when applications want to pay for an order created using the Orders API:

• Use the Payments API (CreatePayment endpoint). To apply a single payment to an order, applications can use the CreatePayment endpoint. In the request, you can specify order_id to attach an order to the payment. The value of the payment (the amount_money field) must exactly match the value of the total_money field of the order. Therefore, this approach works when paying for an order using a single payment.

• Use the Orders API (PayOrder endpoint). To apply multiple payments to an order, applications must use the PayOrder endpoint. These payments must be previously authorized (see Delayed capture of a card payment).

$0 payments

Suppose you create an order for $20 and apply a $20 discount. You then need to make a $0 payment to set the order state to COMPLETED. You can do this using either the Payments API or the Orders API to make a $0 payment. When using the Payments API, you call the CreatePayment endpoint to record a $0 CASH or EXTERNAL payment.

For more information, see Pay for Orders.

View payments in the Seller Dashboard

In production, payments you take using CreatePayment appear in the Seller Dashboard. However, if you are testing the Payments API in the Square Sandbox, the payments appear in the Sandbox Seller Dashboard. For more information, see Sandbox Seller Dashboard.