Take Payments
The Payments API is the backend component of the Square Developer Platform payment solution. The API is responsible for creating and completing (or capturing) payments whose source is provided by a Square client SDKs. These sources can include a credit card, gift card, digital wallet, or ACH bank transfer.
The Payments API provides the CreatePayment endpoint to take a payment. When the CreatePayment
request is successfully processed, the endpoint creates a Payment object and returns it in the response. The returned Payment
object does not always represent a completed payment whose funds have been credited to the seller Square balance. The Payment
has a status
field that indicates the completion state of the payment.
The Payments API can process the following kinds of payments:
Card payments. Charge a card (a credit/debit card or Square gift card). For more information, see Take Card Payments.
ACH bank transfer payments. For more information, see ACH Bank Transfer Payment.
Afterpay payments. For more information, see Afterpay Payments.
Digital wallet payments. For more information, see Digital Wallet Payments.
Square processes these payments and deposits the funds in the seller account Square balance. The seller has options to get the funds. They can set the Square balance to pay the funds out to their bank account. They can also get a Square debit card with access to funds in their Square balance. For more information, see Square Checking.
The Payment object includes a status
field. The status
field value can be:
APPROVED
. The payment is authorized and awaiting completion or cancellation.COMPLETED
. The payment is captured and funds are credited to the seller.CANCELED
. The payment is canceled and the payment card funds are released.FAILED
. The payment request is declined by the bank.
For more information about payment status, see Take Card Payments.
You can use this endpoint to direct Square to take payments and record payments processed outside of Square.
Record payments processed outside of Square. These can be:
Cash payments. A seller can receive cash payments from a buyer and use
CreatePayment
to record the payment. For more information, see Take Cash Payments.External payments. External payments refer to any payments processed by external entities (not by Square or the Square seller). For example, a buyer places a food order through a courier service. The courier service collects the payment and pays the seller. The seller can record these payments using
CreatePayment
. This does not change the seller's Square balance. For more information, see Take External Payments.
Did you know?
You can use payment webhooks to get notification when a buyer makes a payment to the seller who is signed in to your application. The payments can be made using a Square API-enabled application or a Square product such as Square Point of Sale, Square Terminal, Square Invoice, or any other Square product.
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:
The CreatePayments
and ListPayments
endpoints take optional location_id
parameters. When those parameter values are omitted, Square uses the seller default location ID.
The CreatePayment
endpoint request has an optional location_id
field that records the seller's location where a payment is taken. When the field is empty, Square assigns the payment to the seller's default location. If you want to record the payment at one of a seller's other locations, set the field value to that location ID.
If you do not set a location_id
query limit, the ListPayments
endpoint returns payments recorded for the seller's default location. Note that the ListPayments
endpoint cannot return payments for all locations. Results are from only the default location or the location that you specify.
The minimum payment amount you can specify in CreatePayment
and UpdatePayment
requests varies depending on the payment source.
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).
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, call the CreatePayment
endpoint to record a $0 CASH
or EXTERNAL
payment.
For more information, see Pay for Orders.
In production, payments completed using CreatePayment
appear in the . If you test the Payments API in the Square Sandbox, they appear in the . For more information, see Square Sandbox.
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 UpdatePayment
and CompletePayment
endpoints.
Each Payment
includes a version_token
field that uniquely identifies a specific version of the payment. You can include this version_token
in payment operations such as UpdatePayment
and CompletePayment
. In this case, the request succeeds only if the payment has not been updated since that version_token
was generated. If a failure occurs, the error response gives your application an opportunity to fetch the current version of the Payment
object and retry the update.
Note
If you exclude the version_token
from the update request, Square does not use optimistic concurrency, which means the update is applied in a last-write-wins manner. Your application is not notified if your update is overwritten by a newer update unless you have subscribed to the payment_updated
webhook event.
The Payments API offer additional flexibility, including:
Many payment source options. You can charge a payment token generated on a web client by the Web Payments SDK, a card on file, or a gift card on file.
Delayed payments. Using the Payments API, you might only obtain payment authorization and then complete the payment later.
Partial payments with a Square Gift Card. If a buyer provides a gift card as a payment source and the gift card does not have sufficient funds, you can take a partial amount and ask the buyer for additional payment with other cards.
Earn application fees. If a seller pays for use of your application with a periodic fee, use the application fee capability of Payments API.Payments API provides for an application fee to be accrued to your developer account for each payment that Square processes through your application. For more information about using the Payments API to take application fees, see Take Payments and Collect Fees.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.