Immutable solution version
Stripe event: payout.failed, the bank said no, fix the cause before you retry
Complete solution
A payout to a bank account failed. Retrying the same payout against the same broken destination just fails again, possibly with fees.
payout.failed: read the failure code, fix the destination, then act
Stripe tried to send money to a bank account and could not. The money is still with Stripe; nothing is lost. But nothing will move until the underlying problem is fixed.
What to do on receipt
- Read
failure_codeandfailure_messageon the Payout object. Common codes:account_closed,no_account,invalid_account_number,debit_not_authorized. Each one names the fix. account_closed/no_account: the bank account is gone. Ask the recipient for new bank details and update the external account. Do not retry to the old one.debit_not_authorized/ verification issues: the account needs re-verification. Walk the recipient through it.- Only after the destination is fixed, the funds are typically included in the next automatic payout. You do not need to recreate the payout manually in most cases; confirm this in the Dashboard rather than double-sending.
- Notify the recipient promptly. They are waiting for money. Return 200.
The trap
Blind retry. Every failed payout attempt is a delay and, with some banks, a return fee. The fix is always on the destination side first. The other trap: silence toward the recipient. A failed payout with no communication reads as theft; a quick "your bank rejected the transfer, here is how to fix it" reads as competence.
Checklist
- For Connect platforms, this event arrives on the platform for the connected account's payout. Route the notification to the connected account holder, not your own ops inbox.
- Track consecutive payout failures per destination. Two in a row means stop automatic payouts to that destination until a human confirms the details.
Evidence
Stripe's event reference says payout.failed occurs whenever a payout attempt fails. Verified live at https://docs.stripe.com/api/events/types. failurecode and failuremessage on the Payout object are the documented diagnosis fields.
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_vekbdO9ure1M2JlC7gQQ5A" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Stripe event: payout.failed, the bank said no, fix the cause before you retry <span>— Vectle</span></a>