Use the Refunds API to refund a payment processed by Square. You usually need the payment.id value and the amount to refund. In very limited cases, you can refund money to a buyer without referencing a payment ID. This is known as an unlinked refund. Regardless of whether the payment was taken with a Square product or with your application, you can refund a payment using the Refunds API.
The ability to process a refund has the following limitations:
- There is a limit of 20 refunds per payment ID.
- The Refunds API cannot refund payments whose original payment date is more than 1 year ago.
- You cannot refund more than what was originally collected.
- You can only refund payments with the status of
COMPLETED. For a card payment, you cannot refund anAPPROVEDpayment; however, you can cancel anAPPROVEDcard payment. - When you perform an unlinked refund to a Square gift card, Square's enforced compliance limits for gift card activities still apply for digital or physical gift cards.
In the following example RefundPayment request:
payment_ididentifies the payment being refunded.amountspecifies 100 (100 cents or 1 dollar), which is the amount being refunded. Theamountis the smallest denomination of the specified currency.currencyspecifies USD, which is the currency of the refund.Authorizationis the header, which includes the account that took the original payment.
Refund payment
When Square receives the request, it begins the refund process. Square records the refund by creating a PaymentRefund object and returns it in the response. The following is an example response:
{
"refund":{
"id":"6aVfI...",
"status":"PENDING",
"amount_money":{
"amount":100,
"currency":"USD"
},
"payment_id":"sXps2bKrr05VXDaOV0dgexample",
"order_id":"NF446edlDGTq7fzlEzYKSvHJ6xbZY",
"created_at":"2019-07-15T00:25:08.275Z",
"updated_at":"2019-07-15T00:25:08.978Z",
"location_id":"X9XWRESTK1CZ1"
}
}Did you know?
When you refund a payment, Square also creates an Order object that provides the refund details. For more information, see Order Returns and Exchanges.
In the response, note that order_id refers to the Order object created by the refund.
You can create partial payment refunds against a single Payment object. Each partial refund reduces the payment.amount_money.amount value by the refunded amount. The amount_money and refunded_money objects show the payment and refund amounts for a given payment in the following example:
"amount_money": { "amount": 200, "currency": "USD" }, "refunded_money": { "amount": 150, "currency": "USD" }
Note
The refunded_money field only appears on Payment objects when any amount is refunded. Regardless of whether a payment is partially or fully refunded, the payment status remains COMPLETED.
The RefundPayment endpoint supports optimistic concurrency, which ensures that a payment is refunded only if it hasn't been modified after you retrieved it. Each Payment object includes a version_token field that identifies a specific version of the payment. You can choose to include the Payment version token of the payment to be refunded by adding the payment_version_token field in a RefundPayment request. In this case, the refund request succeeds only if the payment hasn't been updated since that version_token was generated.
After you request a payment refund using RefundPayment, the response might show the status as PENDING because Square is still processing the refund. You can send a subsequent GetPaymentRefund request to get the current status.
Did you know?
If you've subscribed to refund webhooks, you get a refund.updated notification with each refund status change.
The PaymentRefund request includes the status field. The status field is the current state of the refund process and can be FAILED, PENDING, COMPLETED, or REJECTED.
FAILED- The refund has failed. The cardholder doesn't receive a refund. The seller can refund the cardholder by other means (such as cash, gift card, or check). Reasons for refund failures can include:- A lack of funds in the seller's account.
- The card receiving the refund isn't valid.
- Invalid request parameters.
PENDING- Square is processing the refund. Square is getting funds from the seller's Square account or is in the process of moving funds back to the buyer's payment card. Most refunds are completed within a few hours. For card and bank transfer payments, the maximumPENDINGtime is 14 days. A seller should contact Square Support if a refund isPENDINGbeyond 14 days.COMPLETED- Square approved the refund and funds have been sent to the buyer's payment card. The cardholder is guaranteed the refund amount. It might take 7–10 business days for refunds to appear, depending on the bank.REJECTED- The refund failed due to a lack of funds in the seller's account and Square was unable to get the funds from the seller's linked bank account. The seller can refund the cardholder by other means (such as cash, gift card, or check).Note
In some cases, a refund can bypass the
PENDINGstate and go directly to theCOMPLETEDorREJECTEDstate. For example, in Japan, due to bank capabilities, refunds move immediately and bypass thePENDINGstate.
The following shows an example refund request:
Get payment refund
The following is a sample response. It shows the refund status as COMPLETED.
{
"refund": {
"id": "h4QWkOP9DASmgeLb7U6cdlonZPUZY_6B9e4Rh1ScERdoKR3jdg8eegxGfy2aXwafaZzogyA3R",
"status": "COMPLETED",
"amount_money": {
"amount": 2000,
"currency": "USD"
},
"payment_id": "h4QWkOP9DASmgeLb7U6cdlonZPUZY",
"order_id": "Sm6psjPEhyowBJeAZxNFVSaw3RNZY",
"created_at": "2020-11-10T22:28:10.282Z",
"updated_at": "2020-11-10T22:28:13.443Z",
"processing_fee": [],
"location_id": "S8GWD5R9QB376",
"reason": "test"
}
}