Take Payments

Applies to: Payments API | Orders API

Learn how to direct Square to take payments and record payments processed outside of Square.

Link to section


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 SDK. These sources can include a credit card, gift card, digital wallet, or ACH bank transfer.

Link to section

Earn application fees

The Payments API lets you earn an application fee each time a seller accepts a payment with your application. An application fee is accrued in your Square account for each payment that Square processes through your application when using the Payments API. For more information about taking application fees, see Collect Application Fees.

Link to section

Payment source types

The Payments API can process or retrieve the following types of payments:

Square processes these payments and deposits the funds in the seller's Square account. The seller has options to get the funds. They can set the Square account to pay the funds to their bank account. They can also get a Square debit card with access to funds in their Square account. For more information, see Square Checking.

Link to section

Accept payments in your application

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 Payment has a status field that indicates the completion state of the payment.

The exception is the House Account payment. You cannot accept this kind of payment in your application. You can only retrieve house account payments that have been completed in the Square Point of Sale.

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

To learn how to use the CreatePayment endpoint, see Card 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.

Link to section

Payment location

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

  • In a CreatePayment request, if a location ID isn't provided, Square assumes the default location of the seller. In a third-party application scenario, it's the default location of the seller for whom the application is taking the payment.
  • In a ListPayment request, if a location ID isn't 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:

  1. Go to the Developer Dashboard.
  2. Choose your application.
  3. In the left pane, choose Locations.
  4. In the list, find the default location name.

The CreatePayments and ListPayments endpoints take optional location_id parameters. When those parameter values are omitted, Square uses the seller's default location ID.

Link to section

Create payments

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.

Link to section

List payments

If you don't 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.

Link to section

Offline payments

If you receive a payment while using Offline Mode, the Payment object returns true for is_offline_payment. This field marks a payment taken as offline. For more information, see Process Card Payments with Offline Mode.

Link to section

Monetary amount limits

The minimum payment amount you can specify in CreatePayment and UpdatePayment requests varies depending on the payment source.

Link to section

Card payment minimums

CountryMinimum payment
France0.01 EUR
Ireland0.01 EUR
United Kingdom£0.01
United States$0.01
Link to section

ACH payment minimums

CountryMinimum payment
United States$0.01
Link to section

Cash payment and external payment minimums

CountryMinimum payment for cash/external payments
AustraliaCash: $0 (the amount can only be specified in increments of $0.05.) External: $0
CanadaCash: $0 (the amount can only be specified in increments of $0.05). External: $0
France0 EUR
Ireland0 EUR
United Kingdom£0
United States$0
Link to section

Afterpay minimums and maximums

CountryMinimum paymentMaximum payment
United Kingdom£1.00£1,000
United States$1.00$2,000
($4,000 for Afterpay monthly payments)
Link to section

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

Link to section

$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 make a $0 payment using the Payments API or the Orders API. When using the Payments API, call the CreatePayment endpoint to record a $0 CASH or EXTERNAL payment.

For more information, see Pay for Orders.

Link to section

View payments in the Seller Dashboard

In production, payments completed using CreatePayment appear in the Seller Dashboard. If you test the Payments API in the Square Sandbox, they appear in the Sandbox Seller Dashboard. For more information, see Square Sandbox.

Link to section

Payment versioning

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 hasn't 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.


If you exclude the version_token from the update request, Square doesn't use optimistic concurrency, which means the update is applied in a last-write-wins manner. Your application isn't notified if your update is overwritten by a newer update unless you have subscribed to the payment_updated webhook event.

Link to section

Payments API flexibility

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 doesn't have sufficient funds, you can take a partial amount and ask the buyer for additional payment with other cards.