You can use the Payments API CreatePayment endpoint to direct Square to take payments and record payments processed outside of Square.
Payments API

Take Payments

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.

You can use this endpoint to direct Square to take payments and record payments processed outside of Square.

  • Direct Square to take payments. These can be:

    Square processes these payments and deposits the funds in the Square balance associated with the seller's account. The seller has various options to access the funds. For example, the seller can configure the Square balance to transfer funds to their bank account or get a Square debit card that provides instant access to funds in the Square balance. For more information, see Square Checking.

  • 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 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 the Point of Sale, Square Terminal, Square Invoice, or any other Square product.

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 the status value set to COMPLETED.

  • If the CreatePayment request specifies autocomplete to false (requesting only payment authorization), the resulting Payment object has the status value 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, APPROVED 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 funds movement (the seller already has the funds).

  • COMPLETED:

    • For card payments, the process to capture the funds with the cardholder's bank has been 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 funds 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.

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:

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

CountryMinimum payment
Australia$1.00
Canada$0.01
France1.00 EUR
Ireland1.00 EUR
Japan¥100
United Kingdom£1.00
United States$0.01

CountryMinimum payment
United States$0.01

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

CountryMinimum paymentMaximum payment
Australia$1.00$2,000
Canada$1.00$2,000
United Kingdom£1.00£1,000
United States$1.00$2,000

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

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.

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.

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 Square Sandbox.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.