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.
You can get a specific refund, given a valid PaymentRefund.id, or you can request a list of refunds filtered by location ID and other values.
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.
{
"refund": {
"id": "bF2xukuBtkb8dOntixQhMeIC_qJbFeWF0lInqOrzPL",
"status": "COMPLETED",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"payment_id": "5g0hWn5rIggRnXcvUGY01l7H4sNZY",
"order_id": "6MAuhu2PP6D3HY56lwO3CHtJd7LZY",
"created_at": "2023-03-13T21:23:04.488Z",
"updated_at": "2023-03-13T21:23:07.403Z",
"processing_fee": [],
"location_id": "VJN4XSBFTVPK9",
"destination_type": "CARD"
}
}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.
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.
{
"refunds": [
{
"id": "5g0hWn5rIggRnXcvUGY01l7H4sNZY_vmlADPqIUDCtJJVdmQgmW58imZ7n3er5IUmWcIluOZC",
"status": "COMPLETED",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"payment_id": "5g0hWn5rIggRnXcvUGY01l7H4sNZY",
"order_id": "6MAuhu2PP6D3HY56lwO3CHtJd7LZY",
"created_at": "2023-03-13T21:23:04.777Z",
"updated_at": "2023-03-13T21:23:07.396Z",
"processing_fee": [],
"location_id": "VJN4XSBFTVPK9",
"destination_type": "CARD"
}
],
"cursor": "nAZ9eiKhOEeXRCZACAsH3dmm9Q1w...scoBqfeqi4jqPeqy3rjSuhHf"
}If you need to get the Order associated with a PaymentRefund, use the PaymentRefund.order_id field as a path parameter in your request.
Note
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.
{
"order": {
"id": "6MAuhu2PP6D3HY56lwO3CHtJd7LZY",
"location_id": "VJN4XSBFTVPK9",
"created_at": "2023-03-13T21:23:04.544Z",
"updated_at": "2023-03-13T21:23:07.000Z",
"state": "COMPLETED",
"version": 4,
"closed_at": "2023-03-13T21:23:04.941Z",
"returns": [
{
"uid": "Bre6c4lWXQIiTI4MvekKXD",
"source_order_id": "yavR3HdLWE1vJlzlvDTF6cqJgrZZY",
"return_line_items": [
{
"uid": "xPuGWbCYekQtkxjc5CGZp",
"quantity": "1",
"item_type": "CUSTOM_AMOUNT",
"base_price_money": {
"amount": 100,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 100,
"currency": "USD"
},
"gross_return_money": {
"amount": 100,
"currency": "USD"
},
"total_tax_money": {
"amount": 0,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 100,
"currency": "USD"
}
}
]
}
],
"return_amounts": {
"total_money": {
"amount": 100,
"currency": "USD"
},
"tax_money": {
"amount": 0,
"currency": "USD"
},
"discount_money": {
"amount": 0,
"currency": "USD"
},
"tip_money": {
"amount": 0,
"currency": "USD"
},
"service_charge_money": {
"amount": 0,
"currency": "USD"
}
},
"refunds": [
{
"id": "vmlADPqIUDCtJJVdmQgmW58imZ7n3er5IUmWcIluOZC",
"location_id": "VJN4XSBFTVPK9",
"transaction_id": "yavR3HdLWE1vJlzlvDTF6cqJgrZZY",
"tender_id": "5g0hWn5rIggRnXcvUGY01l7H4sNZY",
"created_at": "2023-03-13T21:23:04Z",
"reason": "Refund via API",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"status": "APPROVED"
}
],
"source": {},
"net_amount_due_money": {
"amount": 0,
"currency": "USD"
}
}
}