Process an Unlinked Refund

Applies to: Refunds API | Web Payments SDK

Learn how to process unlinked refunds with the Refunds API.

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

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

• Unlinked refunds aren't supported in Japan.

• Refunds cannot be processed by a Square account that hasn't been enabled for payment processing.

• The unlinked refund feature is only available for sellers who've been authorized to use it. A seller using your application needs to contact their Square account manager for authorization. When 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 isn't authorized to make unlinked refunds:

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

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's no Square Payment object to represent the original payment.

This unlinked refund is processed the same way as a standard refund. 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.

Use the RefundPayment endpoint to process an unlinked refund to a card. In the request, don't provide a payment ID. Instead, provide values for the following unlinked refund types before processing the refund.

Add the following values to the RefundPayment request for the card refund:

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

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:

{
  "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 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. Card refunds have a card_details field, which contains the refund destination's payment card details that you can use to confirm with the buyer that the funds were refunded to the intended card.

Add the following values to the RefundPayment request for the cash refund:

• destination_id - Must be CASH.
• location_id - Where the refund occurred.
• unlinked - Must be true.
• cash_details - Must include the amount of cash the seller provided as seller_supplied_money.

The following is an example RefundPayment request:

After receiving the request, Square makes a record of the refund and returns a Refund object, as shown in the following example:

{
  "refund": {
    "id": "9YBgvKvpjwsfM4lT1FjpXBdI...fAGf0A9ueKAqWCHxmQotH8TWjor9ZYfI",
    "status": "PENDING",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "order_id": "6MnVDc5q4xpivpp6LED7FWYNGdZZY",
    "created_at": "2024-10-17T21:08:06.847Z",
    "updated_at": "2024-10-17T21:08:06.856Z",
    "location_id": "{LOCATION_ID}",
    "reason": "Buyer returned goods",
    "unlinked": true,
    "destination_type": "CASH",
    "destination_details": {
      "cash_details": {
        "seller_supplied_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "change_back_money": {
          "amount": 0,
          "currency": "USD"
        }
      }
    }
  }
}

Add the following values to the RefundPayment request for the external refund:

• destination_id - Must be EXTERNAL.
• location_id - Where the refund occurred.
• unlinked - Must be true.
• external_details - Must include:
  • source - A description of the external refund source.
  • type - See accepted options.

The following is an example RefundPayment request:

After receiving the request, Square makes a record of the refund and returns a Refund object, as shown in the following example:

{
  "refund": {
    "id": "9YBgvKvpjwsfM4lT1FjpXBdI...fAGf0A9ueKAqWCHxmQotH8TWjor9ZYfI",
    "status": "PENDING",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "order_id": "6MnVDc5q4xpivpp6LED7FWYNGdZZY",
    "created_at": "2024-10-17T21:08:06.847Z",
    "updated_at": "2024-10-17T21:08:06.856Z",
    "location_id": "{LOCATION_ID}",
    "reason": "Buyer returned goods",
    "unlinked": true,
    "destination_type": "EXTERNAL",
    "destination_details": {
      "external_details": {
        "type": “OTHER”,
        "source": "Food Delivery Service"
      }
    }
  }
}