Learn how to process refunds with the Square Refunds API.
Refunds API

Refund Payments

Use the Refunds API and the RefundPayment endpoint to refund payments. You usually need the Payment ID and the amount to refund. In very limited cases, you can refund money to a buyer without referencing a payment ID as an "unlinked refund". Regardless of how the payment was taken (see Take Payment), you can refund a payment using the Refunds API. Note that when you refund a payment, the Refunds API creates an Order object that provides refund details. For more information, see Order Returns and Exchanges.

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:

  • The Refunds API allows you to refund a payment within 1 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 are 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 of 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 API and Refunds API Overview.

In the following example RefundPayment request:

  • payment_id identifies the payment being refunded.

  • amount_money specifies 1 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: 2023-01-19' \
  -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:

In the response, note that order_id refers to the Order object created by the refund.

Note that Square supports optimistic concurrency for the RefundPayment endpoint. Each Payment includes a version_token field that uniquely identifies a specific version of the payment. You can optionally 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 has not been updated since that version_token was generated.

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: 2023-01-19' \
  -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.

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

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. Square handles most refunds within a few hours. Some might take longer. For card and bank transfer payments, the maximum amount of time a refund can stay in the PENDING state is 14 days. You should contact Square support if a refund remains in the PENDING state beyond 14 days.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 the COMPLETED or REJECTED state. For example, in Japan, due to bank capabilities, refunds move immediately and bypass 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).

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

Note

Unlinked refunds are not supported in Japan.

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 Retrieve a specific location feature 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:

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:

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.

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 Balance is the source of the funds for the refund. If there is an insufficient balance, the seller's linked bank account is the refund's source.

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-01-19' \
  -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.

For unlinked refunds, the following destinations are supported:

  • Card. The exception is American Express, which is not supported.

  • Square gift card.

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

  • Square allows unlinked refunds for only 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.

  • American Express payment cards are not supported for unlinked refunds.

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

    The following example is the 400 response that your application receives if used by a seller who is not authorized to make unlinked refunds:

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