Refund fails with INSUFFICIENT_REFUNDABLE_AMOUNT even though the payment has never been refunded and the account balance is sufficient

Questions
1

Hello,

We are a Japan-based seller (currency: JPY) using the Refunds API to issue a full refund. The refund keeps failing with the error below, and we cannot find the reason.

Environment

  • Production
  • Square-Version: 2025-01-23
  • PHP SDK: square/square 40.0.0.20250123
  • Endpoint: POST /v2/refunds

Affected payment

  • Paid at: 2026-03-22 21:13 JST
  • Paid amount: 8,400 JPY
  • Refund amount: 8,400 JPY (full)

The payment was made through the API and has never been refunded, fully or partially. I can share the IDs privately if needed.

Request (2026-10-08 11:10:23 JST)

The reason means “refund due to cancellation”.

POST /v2/refunds
content-type: application/json
square-version: 2025-01-23
user-agent: Square-PHP-SDK/40.0.0.20250123 (2025-01-23) PHP/8.4.21 (Linux-6.1.174-217.345.amzn2023.x86_64)

{
  "idempotency_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "amount_money": {
    "amount": 8400,
    "currency": "JPY"
  },
  "payment_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "reason": "xxxxxx"
}

Response (400)

date: Thu, 08 Oct 2026 02:10:23 GMT
square-version: 2025-01-23
content-type: application/json

{
  "errors": [
    {
      "code": "BAD_REQUEST",
      "detail": "Return line items could not be reserved; reason=INSUFFICIENT_REFUNDABLE_AMOUNT.",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

Timeline

  • The refund has failed once a day since 2026-09-28. The latest attempt was at 2026-10-08 11:10:23 JST.
  • Other refunds through the same code path succeeded until 2026-09-20.
  • Refunding from the Seller Dashboard also fails, with a message saying that the account balance is less than the refund amount.

Balance

  • On 2026-10-08 the available balance was 24,581 JPY, which is more than the refund amount (8,400 JPY), but the refund still failed.

Questions

  1. What does INSUFFICIENT_REFUNDABLE_AMOUNT mean in this case? Does it refer to the refundable amount of the order/payment, or to the account balance?
  2. Which balance is used for refunds, and when do new sales become usable for refunds?
  3. How can we complete this refund?

Any help would be appreciated. Thank you.

3

Thanks for the details. Since the refund also isn’t working in Dashboard, we’ll need to investigate the specific payment before confirming the cause. I will DM you to get the payment ID and location ID.