Refunds API

Refund Payments

You use the Refunds API and the RefundPayment endpoint to refund payments. You need the Payment ID and the amount to refund. Regardless of how the payment was taken (see Take Payment), you can refund a payment using the Refunds API.

Some of the common refund scenarios include:

  • Refund all or a portion of a payment.

  • Multiple partial refunds of a payment.

The following applies to refunds:

  • Refund API allows you to refund a payment within one year of the original payment date.

  • You cannot refund more than what was originally collected.

  • The refund amount must be available in the Square account. If it is not, Square attempts to take money out of the associated bank account. Refunds are in a state of PENDING until the funds can be secured. If funds cannot be secured, the refund is not completed and the buyer does not receive a credit. The refund has a status of FAILED. Future refunds to this payment are not allowed and the buyer should be reimbursed by other means.

  • You can only refund payments with the status COMPLETED. For a card payment, you cannot refund an APPROVED payment; however, you can cancel an APPROVED card payment.

This topic explores the API and provides examples. For an overview, see Payments and Refunds APIs Overview.

Refund a payment Permalink Get a link to this section

In the following example RefundPayment request:

  • payment_id identifies the payment being refunded.

  • amount_money specifies one dollar to refund. It also specifies the currency and the amount to charge. The amount is the smallest denomination of the specified currency (USD), which means the US dollar amount specified in the request is in cents (100 cents).

  • Authorization header includes the account that took the original payment.

Refund Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
curl https://connect.squareupsandbox.com/v2/refunds \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "payment_id": "{PAYMENT_ID}",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    }
  }'

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

Retrieve refund information Permalink Get a link to this section

After you refund a payment, the RefundPayment response might show the status as PENDING. You can send a GetPaymentRefund request to get refund information.

Get Payment Refund
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/refunds/{refund_id} \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is a sample response. It shows the refund status as COMPLETED. For different status values, see PaymentRefund.

{
  "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": [
      {
        "effective_at": "2020-11-11T00:26:19.000Z",
        "type": "INITIAL",
        "amount_money": {
          "amount": -88,
          "currency": "USD"
        }
      }
    ],
    "location_id": "S8GWD5R9QB376",
    "reason": "test"
  }
}

Refund status Permalink Get a link to this section

When you refund a payment using RefundPayment, you get a PaymentRefund object in the response which includes the status field. The status field can be PENDING, COMPLETED, REJECTED, or FAILED.

  • FAILED. If the request fails, the status value is set to FAILED. Request failures can be caused by, for example, a lack of funds in the seller's account, the card receiving the refund is no longer valid, and bad request parameters. Otherwise, status is set as follows.

  • PENDING. Square is processing the refund. For example, Square is requesting funds from the seller or is in the process of moving funds. The status can change to:

    • COMPLETED. Square has approved the refund and funds are being sent to the buyer.

    • 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.

    Note

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

In terms of the cardholder receiving funds, the RefundPayment object's status values indicate the following:

  • PENDING. The funds are requested.

  • COMPLETED. The cardholder is guaranteed the refund amount. It might take 7–10 business days for refunds to appear depending on the bank.

  • REJECTED. The cardholder does not receive a refund. The seller can refund the cardholder by other means (such as cash, gift card, or check).

  • FAILED. The cardholder does not receive a refund. The seller can refund the cardholder by other means (such as cash, gift card, or check).