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

In a CreatePayment request, you specify amount_money and tip_money. The amount_money indicates the amount of money to accept for the payment, not including tip_money.

Both the amount_money and tip_money include the amount value and the currency. The amount value you provide is in the smallest denomination of the currency indicated by the currency field. For example:

• When currency is USD, the amount is in cents.

• When currency is GPB, the amount is in pence.

The following table shows the minimum amount that CreatePayment accepts.

The minimum amount in the table refers to the total of amount_money and tip_money combined. For example, in the UK (currency is GPB), you can call CreatePayment to accept 50 amount_money and 50 tip_money, for a total of 100.

For information about maximum charge amounts, see Seller community: General discussion.

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:

• Pay using the Payments API (CreatePayment endpoint). In a CreatePayment request, you can specify order_id to attach an order to the payment. The value of the payment (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.

• Pay using the Orders API (PayOrder endpoint). You use this endpoint to pay for an order for the following reasons:

  • Apply multiple payments to an order. These payments must be previously authorized (see Delayed capture of a card payment).

  • Make a $0 payment to complete an order. For example, 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.

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.