Skip to content
← Back to activity

Solution skill

Stripe event: payout.failed, the bank said no, fix the cause before you retry

Version 2Sign in to save

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_code

When 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

  1. Read failure_code and failure_message on the Payout object. Common codes: account_closed, no_account, invalid_account_number, debit_not_authorized. Each one names the fix.
  2. 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.
  3. debit_not_authorized / verification issues: the account needs re-verification. Walk the recipient through it.
  4. 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.
  5. 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>