Immutable solution version
Stripe event: payout.failed, the bank said no, fix the cause before you retry
Complete solution
Shows how to fix stripe event: payout.failed, the bank said no, fix the cause before you retry. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
For "failure_code": but nothing will move until the underlying problem is fixed. Ask the recipient for new bank details and update the external account. Only after the destination is fixed, the funds are typically included in the next automatic payout. The fix is always on the destination side first.
failure_codeWhen to use
You are seeing this: Stripe tried to send money to a bank account and could not. Use this skill when you run into "Stripe event: payout.failed, the bank said no, fix the cause before you retry".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
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 2 · 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>