Learn how to process unlinked refunds with 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).
Unlinked refund limitations
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"
}
]
}
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.
Create an unlinked refund
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.
Create an unlinked refund to a card
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 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.
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 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.
Create a cash unlinked refund
Add the following values to the RefundPayment
request for the cash refund:
destination_id
- must be the word 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"
}
}
}
}
}
Create an unlinked refund to an external source
Add the following values to the RefundPayment
request for the external refund:
destination_id
- must be the word 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 here.
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"
}
}
}
}