Retrieve Payments

Applies to: Payments API | Orders API | Reader SDK | Checkout API | Point of Sale API | Invoices API | Subscriptions API

Learn how to retrieve payments using the GetPayment or ListPayments endpoint.

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, Square 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's 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 10 PM.
• 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 are fewer than 10 payments in the response, it doesn't include a cursor field to fetch the next page of results.

If a buyer makes a payment on the Square Terminal through a Terminal checkout request, the Payment object includes the terminal_checkout_id read-only value that represents the Terminal checkout. The terminal_checkout_id value associates the Terminal checkout with the payment.

{
  "payment": {
    "id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY",
    "created_at": "2024-09-19T21:14:29.577Z",
    "updated_at": "2024-09-19T21:14:30.504Z",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "app_fee_money": {
      "amount": 10,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "delay_duration": "PT168H",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "VISA",
        "last_4": "1111",
        "exp_month": 11,
        "exp_year": 2042,
        "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ",
        "card_type": "DEBIT",
        "prepaid_type": "NOT_PREPAID",
        "bin": "411111"
      },
      "entry_method": "ON_FILE",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "auth_result_code": "vNEn2f",
      "statement_description": "SQ *EXAMPLE TEST GOSQ.C",
      "card_payment_timeline": {
        "authorized_at": "2021-10-13T21:14:29.732Z",
        "captured_at": "2021-10-13T21:14:30.504Z"
      }
    },
    "location_id": "L88917AVBK2S5",
    "order_id": "pRsjRTgFWATl7so6DxdKBJa7ssbZY",
    "reference_id": "123456",
    "risk_evaluation": {
      "created_at": "2021-10-13T21:14:30.423Z",
      "risk_level": "NORMAL"
    },
    "terminal_checkout_id": "08YceKh7B3ZhO",
    "note": "Brief Description",
    "customer_id": "W92WH6P11H4Z77CTET0RNTGFW8",
    "total_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "approved_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "receipt_number": "R2B3",
    "receipt_url": "https://squareup.com/receipt/preview/EXAMPLE_RECEIPT_ID",
    "delay_action": "CANCEL",
    "delayed_until": "2021-10-20T21:14:29.577Z",
    "application_details": {
      "square_product": "ECOMMERCE_API",
      "application_id": "sq0ids-TcgftTEtKxJTRF1lCFJ9TA"
    },
    "version_token": "TPtNEOBOa6Qq6E3C3IjckSVOM6b3hMbfhjvTxHBQUsB6o"
  }
}