Stripe Refund

Five statuses, and only one of them means the customer has the money

Stripe lists the values plainly: "Status of the refund. This can be `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`." Three of those five describe a refund that exists in your account but has not landed with the customer, and each has a different cause.

`pending` has its own explanatory field. Stripe documents `pending_reason` as: "Provides the reason for why the refund is pending. Possible values are: `processing`, `insufficient_funds`, or `charge_pending`." Those are three genuinely different situations. `processing` is ordinary waiting. `insufficient_funds` means the refund is queued against a balance that cannot cover it yet, which is a cash-position problem rather than a payments problem. `charge_pending` means the original money has not finished settling, so there is nothing to send back yet.

`requires_action` is the one most people have never seen, and Stripe points at the field that explains it: `next_action` is documented as what applies "If the refund has a status of `requires_action`", describing "what the refund needs to continue processing." For payment methods without native refund support, that action can involve the customer directly. Stripe documents `instructions_email` as the place to "provide an email address for the customer to receive refund instructions." A refund in this state is waiting on a human, and no amount of resyncing will move it.

The practical consequence for a month-end close is that a refund list filtered on "exists" overstates what has actually gone back to customers. Filter on `succeeded` when you are reconciling, and treat everything else as a queue to work through.

A refund is funded from your balance, not clawed back from the charge

This is the most common structural misunderstanding, and it explains several behaviours that otherwise look like bugs.

Stripe is explicit about the funding source: "Refunds use your available Stripe balance (not including pending amounts)." The original charge is not reopened and money is not retrieved from it. A refund is a fresh outbound movement, paid for out of whatever you happen to be holding at that moment.

Which is why an empty balance changes the outcome rather than merely delaying it, and Stripe splits the behaviour by payment method: "If your available balance doesn’t cover the amount of the refund, Stripe holds the refund as pending for card transactions (refunds for other payment method types will fail) until your Stripe balance becomes sufficient." A card refund waits. A refund on another method does not wait, it fails. If you process a batch of refunds on a low-volume day, that distinction decides whether you have a queue or a pile of failures.

Two related constraints follow from the same design. Stripe documents that "Refunds can only be sent back to the original payment method used in a charge. You can’t send a refund to a different destination, such as another card or bank account." And on partial refunds: "You can issue more than one refund against a charge, but you can’t refund a total greater than the original charge amount."

One more piece of the economics is easy to miss and lands directly in your books. Stripe states that its "processing fees from the original transaction aren’t returned." A refunded sale is therefore not a neutral event. The revenue reverses, the fee does not, and the difference is a real cost that stays on your profit and loss.

`reason` is your label, `failure_reason` is the outcome

Two fields on the refund object sound similar and are constantly conflated. They are not the same kind of fact, and only one of them tells you anything about whether the refund worked.

`reason` is a categorisation you supply. Stripe documents it as: "Reason for the refund, which is either user-provided (`duplicate`, `fraudulent`, or `requested_by_customer`) or generated by Stripe internally (`expired_uncaptured_charge`)." Three of those four values are whatever the person clicking Refund selected in the Dashboard. It is useful for your own reporting and it is worth applying consistently, but it is a note about intent, not a system determination.

`failure_reason` is the opposite. Stripe documents it as: "Provides the reason for the refund failure. Possible values are: `lost_or_stolen_card`, `expired_or_canceled_card`, `charge_for_pending_refund_disputed`, `insufficient_funds`, `declined`, `merchant_request`, or `unknown`." Every one of those is an outcome reported back by a bank or an issuer, not something you chose.

The distinction has a practical edge. If you are building a report on why money goes back to customers, `reason` is your field, and its quality depends entirely on your team applying it consistently. If you are investigating why a customer says they never got their money, `reason` will tell you nothing at all and `failure_reason` is the only field worth reading.

A failed refund leaves two balance transactions, not zero

Every refund points at its own money record. Stripe documents `balance_transaction` on the refund as the "Balance transaction that describes the impact on your account balance." That is the debit: funds leaving you and heading for the customer.

When a refund fails, that debit is not deleted. A second record is created to undo it. Stripe documents `failure_balance_transaction` as: "After the refund fails, this balance transaction describes the adjustment made on your account balance that reverses the initial balance transaction." So a failed refund is visible in your balance history twice, once going out and once coming back, and the net is zero only when you read both.

The timing is the part that catches people. Stripe describes the mechanics this way: "A refund can fail if the customer’s bank or card issuer can’t process it. For example, a closed bank account or a problem with the card can cause a refund to fail. When this happens, the bank returns the refunded amount to us and we add it back to your Stripe account balance. This process can take up to 30 days from the post date." Thirty days is long enough to cross a close, which means a refund can be recorded in one period and reversed in the next while nothing at all was wrong with your bookkeeping. [When a Stripe refund fails and the money comes back](/blog/stripe-refund-failed-quickbooks) works through that case end to end.

One last fact that sits at the boundary with disputes and is worth knowing before you decide how quickly to refund a complaining customer: Stripe states that "Disputes and chargebacks aren’t possible on credit card charges that are fully refunded."