Refunds API

Refund Payments

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.

Link to section
Limitations

The ability to process a refund has the following limitations:

The Refunds API can't refund payments whose original payment date is more than 1 year ago.
You can't refund more than what was originally collected.
You can only refund payments with the status of COMPLETED. For a card payment, you can't refund an APPROVED payment; however, you can cancel an APPROVED card payment.

Link to section
Refund a payment

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.

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: 2023-05-17' \
  -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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

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.

Link to section
Partial refunds

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

Link to section
Refund the current version of the payment

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.

Link to section
Get the status of a refund

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.

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

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:

Get Payment Refund

curl https://connect.squareupsandbox.com/v2/refunds/{refund_id} \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is a sample response. It shows the refund status as COMPLETED.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

Link to section
Unlinked refunds

An unlinked refund is not linked to a Square payment and has no associated payment ID. Use an unlinked refund when there is no Square payment to link to (such as when the original payment was processed by another payment processor).

Link to section
Unlinked refund limitations

The ability to process an unlinked refund has the following limitations:

Unlinked refunds are not supported in Japan.
American Express card payments cannot be refunded.
Square allows unlinked refunds only for seller accounts that have two-factor authentication (2FA) enabled for all employees.
Refunds cannot be processed by a Square account that has not been enabled for payment processing.
The unlinked refund feature is only available for sellers who have been authorized to use it. A seller using your application needs to contact their Square account manager for authorization. Once authorized, all of the seller's locations can take unlinked refunds.
The following example is the 400 response that your application receives if used by a seller who is not authorized to make unlinked refunds:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
```
 {
   "errors": [
     {
       "code": "BAD_REQUEST",
       "detail": "Unlinked refund processing is not enabled for this merchant.",
       "category": "INVALID_REQUEST_ERROR"
     }
   ]
}
```

Link to section
Determine whether a seller can process unlinked refunds

Before a seller can use the unlinked refund capability of your application, they need to be authorized by Square. Your application needs to determine the status of that capability before rendering any related UI. Use the Locations API (see Retrieve a specific location) to get the list of capabilities for the seller location where your application is signed in. The capabilities field in the returned Location object includes a structure similar the following:

   "capabilities": [
      "CREDIT_CARD_PROCESSING",
      "UNLINKED_REFUNDS"
    ]

If the seller location is enabled for unlinked refunds, the capabilities array includes UNLINKED_REFUNDS. If the capability is not present, unlinked refunds are not enabled. The seller needs to contact their Square account manager for authorization. Without authorization, a request to create an unlinked refund returns the following error:

{
   "errors": [
     {
       "code": "BAD_REQUEST",
       "detail": "Unlinked refund processing is not enabled for this merchant.",
       "category": "INVALID_REQUEST_ERROR"
     }
   ]
}

Your application should subscribe to Locations API webhooks to catch the location.updated event so that if unlinked refunds are enabled for the seller while your application is running, it can refresh its UI to allow unlinked refunds.

Link to section
Refund a non-Square payment

Non-Square payments exist when a seller is transitioning their payment processing from another service to Square. During the transition period, the seller might want to issue a refund through Square for a payment taken before they started with Square. The refund request is unlinked because there is no Square Payment object to represent the original payment.

This unlinked refund is processed in the same way a standard refund is processed. The seller's Square account is the source of the funds for the refund. If there are insufficient funds in the seller's Square account, the seller's linked bank account is the refund's source.

Link to section
Create an unlinked refund

Use the RefundPayment endpoint to process an unlinked refund. In the request, do not provide a payment ID. Instead, provide values for the following fields:

destination_id. Identifies the refund destination by setting the value to a payment card (or Square gift card) token or card on file ID. Specify one of the following:
- A payment token.
- A Square gift card or card on file ID.
location_id. Where the refund occurred.
customer_id. Required for card-on-file destinations.
unlinked. Must be true.

A payment token is generated by your application using the Web Payments SDK. When testing, use a Sandbox testing token such as cnon:card-nonce-ok.

The following RefundPayment request specifies a test payment card on file that Square provides for Sandbox testing. You can test the same request with any of the card test values that Square provides, with the exception of the American Express card, which is not supported for unlinked refunds.

Refund Payment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

curl https://connect.squareupsandbox.com/v2/refunds \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "idempotency_key": "{IDEMPOTENCY_KEY}",
    "location_id": "{LOCATION_ID}",
    "destination_id": "ccof:customer-card-id-mastercard-ok",
    "unlinked": true,
    "reason": "Buyer returned goods",
    "customer_id": "{CUSTOMER_ID}"
  }'

After receiving the request, Square processes the refund and returns money to the buyer. In response, Square returns a Refund object, as shown in the following example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

{
  "refund": {
    "id": "9YBgvKvpjwsfM4lT1FjpXBdI...fAGf0A9ueKAqWCHxmQotH8TWjor9ZYfI",
    "status": "PENDING",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "order_id": "6MnVDc5q4xpivpp6LED7FWYNGdZZY",
    "created_at": "2022-09-24T21:08:06.847Z",
    "updated_at": "2022-09-24T21:08:06.856Z",
    "location_id": "S8GWD5R9QB376",
    "reason": "Buyer returned goods",
    "unlinked": true,
    "destination_type": "CARD",
    "destination_details": {
      "card_details": {
        "card": {
          "card_brand": "MASTERCARD",
          "last_4": "6952",
          "exp_month": 12,
          "exp_year": 2028,
          "fingerprint": "sq-1-HVUCWbGnS2LZ...E8Gkh_EtOTe0A",
          "card_type": "CREDIT",
          "bin": "512081"
        },
        "entry_method": "ON_FILE"
      }
    }
  }
}

The order_id in this example is the unlinked return order ID. Square creates a refund order for you while processing the refund request and returns the new order ID in this response.

The destination_details field contains the details of the refund destination. Currently, payment cards are the only supported refund destination. As additional destination types are supported, the destination_details field will contain one child object for details of the destination type used in the refund.

The destination_details.card_details field contains details of the destination payment card that you can use to confirm to the buyer that the funds were refunded to the intended card.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Refund Payments

Link to section
Limitations

Link to section
Refund a payment

Did you know?

Link to section
Partial refunds

Note

Link to section
Refund the current version of the payment

Link to section
Get the status of a refund

Did you know?

Note

Link to section
Unlinked refunds

Link to section
Unlinked refund limitations

Link to section
Determine whether a seller can process unlinked refunds

Link to section
Refund a non-Square payment

Link to section
Create an unlinked refund

On this page

Docs

Refund Payments

Link to section Limitations

Link to section Refund a payment

Did you know?

Link to section Partial refunds

Note

Link to section Refund the current version of the payment

Link to section Get the status of a refund

Did you know?

Note

Link to section Unlinked refunds

Link to section Unlinked refund limitations

Link to section Determine whether a seller can process unlinked refunds

Link to section Refund a non-Square payment

Link to section Create an unlinked refund

On this page

Link to section
Limitations

Link to section
Refund a payment

Link to section
Partial refunds

Link to section
Refund the current version of the payment

Link to section
Get the status of a refund

Link to section
Unlinked refunds

Link to section
Unlinked refund limitations

Link to section
Determine whether a seller can process unlinked refunds

Link to section
Refund a non-Square payment

Link to section
Create an unlinked refund