Retrieve Payments
Regardless of the payment source (card, cash, or external payments) or what the seller used to process a payment (Square first-party products such as Point of Sale, Seller Dashboard, or a custom application that makes CreatePayment
calls), Square records these payments by creating Payment
objects.
All these payments can be access using the Payments API (GetPayment
or ListPayments
endpoint).
If you have the ID of a payment, you can use the GetPayment
endpoint to retrieve the payment by its ID. When making a REST call, the payment ID is a path parameter. When using one of the Square SDKs, it is a named or position parameter to the GetPayment
function.
A Payment object is returned if you have provided a valid ID. Otherwise, a NOT_FOUND
error is returned with detail: "Could not find payment with id: 5g0hWn5rIggRnX_UGY01l7H4sNZY".
There are several ways to get a payment ID.
Order object. An Order
object is created by Square products such as Square Point of Sale or a Reader SDK integration. If you have an Order
object, use the Order.tenders.payment_id
field value to get a payment.
Reader SDK payment. Payments are recorded as transaction objects. Use the Transaction.order_id
field value to get an Order
. The Order.tenders.payment_id
field value is used to get the payment.
Checkout API payment. With each payment, the Checkout API creates an Order
. The Order.tenders.payment_id
field value is used to get the payment.
Point of Sale API. With each payment, the Point of Sale API creates an Order
. For more information about getting a Payment
object, see Payments API Integration.
Invoice payment. If a buyer paid by invoice, use the Invoices API to get the Invoice
and use the value of the Invoice.order_id
field to get the associated Order
object. The Order.tenders.payment_id
field value is used to get the payment.
Subscription payment. Square subscription payments are made by customers who receive an emailed invoice from Square or pay with a card. You can use the Invoices API to get the Invoice
and use the value of the Invoice.order_id
field to get the associated Order
object. The Order.tenders.payment_id
field value is used to get the payment recorded when the buyer pays the subscription installment.
Your application can retrieve every payment created in the authorized Square account, but that list can be quite large. Instead, you should scope your request to something like the following example.
In this example, the request is filtering on:
A single location.
The card brand is VISA.
The payment date is later than 2023-03-01, at 10pm.
The result page size is 10.
The response object is a list of Payment
objects that meet the filter conditions of the request. If there had been fewer than 10 payments in the response, it would not include a cursor
field whose value is used in a subsequent request to fetch the next page of results.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.