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

Link to section

Get a payment by ID

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.

curl https://connect.squareupsandbox.com/v2/payments/6MAuhu2PP6D3HY56lwO3CHtJd7LZY \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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

Link to section

Get payment IDs

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.

Link to section

Get a list of payment objects

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.

  List Payments

  cURL

  • cURL
  • C#
  • Java
  • PHP
  • Python
  • Ruby
  • Node.js

  Copy

  • 1
  • 2
  • 3
  • 4

  curl https://connect.squareupsandbox.com/v2/payments?begin_time=2023-03-01T22%3A23%3A55.737Z&location_id=VJN4XSBFTVPK9&card_brand=VISA&limit=10&cursor=XlKamNtVmhkR1ZrUVhR_SW1sa0lqb2mRsVkhXVEF4YkRkSU5ITk9XbGtpZlE \
    -H 'Square-Version: 2023-03-15' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json'

  Try in API Explorer

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.