Refund Payments

Applies to: Refunds API | Orders API | Locations API | Web Payments SDK

Learn how to refund a payment processed by Square.

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 an APPROVED payment; however, you can cancel an APPROVED card payment.
• When you perform an unlinked refund or a cross-method 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_id identifies the payment being refunded.
• amount specifies 100 (100 cents or 1 dollar), which is the amount being refunded. The amount is the smallest denomination of the specified currency.
• currency specifies USD, which is the currency of the refund.
• Authorization is the header, which includes the account that took the original 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"
  }
}

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

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.

The PaymentRefund 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 maximum PENDING time is 14 days. A seller should contact Square Support if a refund is PENDING beyond 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). The seller cannot send a refund of a completed payment back to a transportation card; this results in a rejected refund request.

  Note

  In some cases, a refund can bypass the PENDING state and go directly to the COMPLETED or REJECTED state. For example, in Japan, due to bank capabilities, refunds move immediately and bypass the PENDING state.

The following shows an example refund request:

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

You can also use the Refunds API to perform cross-method gift card refunds.

The Refunds API supports cross-method refunds to gift cards if the POST RefundPayment request contains a payment_id of the payment source and a giftcard_id that's used for the destination_id of the refund.

The following restrictions apply to cross-method refunds to gift cards:

• The unlinked field in the RefundPayment request must be false or omitted.
• The customer_id, location_id, and app_fee_money fields in the RefundPayment request must be omitted.
• Only existing PENDING or ACTIVE gift cards can be used as refund destinations. The Refunds API doesn't support creating Square gift cards. If a refund is issued to a PENDING gift card, the card is automatically activated.
• Cross-method refunds to gift cards are available for applications using Square API version 2024-08-21 and later. If the Square API version is earlier than 2024-08-21, the following additional restrictions apply:
  • You cannot create a cross-method refund to a gift card, and you would receive an API_VERSION_INCOMPATIBLE error.
  • You cannot get a cross-method refund made to a gift card with the GetPaymentRefund endpoint. Passing in the refund_id for a cross-method gift card refund results in an API_VERSION_INCOMPATIBLE error.
  • ListPaymentRefunds responses omit cross-method gift card refunds.
  • Responses return payments that omit the refunded_money and refund_id fields for cross-method gift card refunds.

If a refund is rejected, it might be a disputed refund. In this case, the requested payment is no longer eligible for refunds because it's outside of the eligible refund timeframe.

If the refund isn't fulfilled by the eligible refund deadline, the refund is rejected. The application returns a 404: PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE bad request error as a result. If this error occurs, you must cancel the refund request.