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 specifiesautocomplete
totrue
, the payment is processed immediately and the resultingPayment
object hasstatus
set to COMPLETED.If the
CreatePayment
request specifiesautocomplete
tofalse
(requesting only payment authorization), the resultingPayment
object hasstatus
set to APPROVED. You then have the following options:Complete (or capture) the payment by calling
CompletePayment
. This changes thestatus
value to COMPLETED.Cancel the payment by calling
CancelPayment
. This changes thestatus
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:
Go to the Developer Dashboard.
Choose your application.
In the navigation pane, choose Locations.
In the list, find the default location name.
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 (theamount_money
field) must exactly match the value of thetotal_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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.