Retrieve Refunds

Applies to: Refunds API | Payments API

Learn how to retrieve funds regardless of the payment source or what the seller used to process a payment.

Link to section


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, the Seller Dashboard, or a custom application that makes CreatePayment calls), your application can refund these payments by creating a Refund object using the RefundPayment endpoint.

Link to section

Retrieve payment refunds

You can get a specific refund, given a valid, or you can request a list of refunds filtered by location ID and other values.

Link to section

Get a refund object

When a payment is refunded, the Payment object is updated with details that include the amount refunded represented by the Payment.refunded_money child object.

"refunded_money": { "amount": 100, "currency": "USD" }

The Payment also refers to the PaymentRefund object that was created for the payment refund in the Payment.refund_ids child object.

"refund_ids": [ "bF2xukuBtkb8dOntixQhMeIC_qJbFeWF0lInqOrzPL", "bF2xukuBtkb8dOntixQhMeICB_Wg9piDyTF2pP34gyywPorIHvyc" ]

refund_ids is an array because any one payment might have one or more partial refunds, up to the full amount of the payment.

For each payment refund ID, make the following request:

Get payment refund

The PaymentRefund object that is returned shows the amount refunded. If there are multiple refund IDs in the Payment, get each of them and total the amounts in the PaymentRefund.amount_money fields to get the total amount refunded for the payment.

Note the "order_id": "6MAuhu2PP6D3HY56lwO3CHtJd7LZY" field in the PaymentRefund object. Use the field value to get the Order that was created for the refund. This isn't the same Order object that was created for the initial Payment.

Link to section

Get a list of refund objects

Your application can retrieve every payment refund 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 refund status is Completed.
  • The payment type is Card.
  • The refund date is later than 2023-03-01, at 10 PM.
  • The result page size of 10.

List payment refunds

The response object is a list of PaymentRefund objects that meet the filter conditions of the request. If there are fewer than 10 refunds in the response, it doesn't include a cursor field whose value is used in a subsequent request to fetch the next page of results.

Link to section

Retrieve the associated order

If you need to get the Order associated with a PaymentRefund, use the PaymentRefund.order_id field as a path parameter in your request.


If you issue multiple partial payment refunds for a single payment, a separate Order is created for each partial payment refund.

The following example retrieves order 6MAuhu2PP6D3HY56lwO3CHtJd7LZY:

Retrieve order

The response is the Order object with the specified ID. The refunds field contains the details of the refund.