Free Payout Failure Diagnosis
Map failure patterns to root causes, resolution steps, and a prevention checklist. Turn payout-day firefighting into a repeatable runbook.
Failure type
Select the failure status you observed, then answer follow-up questions to get a prioritized recovery runbook.
Recovery runbook
This troubleshooter maps likely root causes and next actions from your inputs; confirm final return codes with provider responses.
Two families of failure, two different clocks
This page is a weighted questionnaire over a fixed list of causes, so it ranks what your answers suggest and reads no code from your provider. The distinction it is built around is worth carrying into a runbook on its own. A payment can fail before anyone accepts it, on validation, a limit or a screening result, and it can fail after acceptance, when the receiving side sends it back. The first kind belongs to you and can be fixed and resubmitted the same afternoon. The second belongs to a bank you have no relationship with and arrives on its own schedule.
Pending is the state that costs the most, because nothing has happened. The payment left, no return has come back, and the payee has been told a date. There is no event to act on, no reason code to look up, and no counterparty who owes you an answer, so the work becomes a person checking a file each morning. The temptation at that point is to send it again, which is how one delayed payment becomes two delivered ones and a conversation about getting money back from somebody who has already spent it.
A workable runbook names an owner per family and a rule for the wait. Bank detail and format problems go back to the payee with the specific field named, since asking for a corrected IBAN gets a faster answer than asking why a payment failed. Screening and document holds sit with whoever can clear them and often cannot be described to the payee in detail. Returns are the only group where the answer lives with the provider. Set a maximum wait before you escalate, write it down, and re-attempt on evidence rather than on pressure from the payee.
How a likely cause is picked
Your answers add weights to a list of candidate causes, and the heaviest one is reported once every question is answered. The weights were written for this page.
What it assumes
- The failure you describe belongs to one of the stored failure types.
- Each answer contributes points to one or more causes, and the ranking is the sum of those points.
- The result appears once every question in the set has an answer, and it names a single cause with its resolution steps and prevention notes.
- A tie goes to whichever of the tied causes picked up its first point earliest in the question set.
What it leaves out
- Provider return codes, which are the authoritative answer and vary by rail and by bank.
- Any connection to your payment provider. Nothing here reads a real transaction.
- Sanctions and compliance holds, which look like technical failures and resolve differently.
- Whether a retry is safe, which depends on idempotency in your own system.
Where the numbers come from
- Cause weights
- Our own assumptionHand-assigned point values written for this page to order the candidates. No published failure-rate dataset stands behind them.
- The failure type and cause lists
- Our own assumptionDrawn from common cross-border payout failure patterns and written as a triage aid. Confirm against the return code your provider gave you.
Assumptions and sources checked 5 September 2026. Published figures move on their own schedule, so confirm anything you rely on against the authority that issues it.
How it works
- 01
Pick the failure type
Rejected, returned, pending, wrong amount, compliance hold, account not found.
- 02
Enter corridor + rail
Country pair and rail so the tool can infer likely return reasons.
- 03
See root causes
Ranked list of likely causes + resolution actions.
- 04
Copy the checklist
Export the prevention steps into your ops runbook.
Related guides
Payout Failure Root Cause Analysis for Bank, User, and Processor Errors at Scale
The formal method behind the one-step mapping: bank, user and processor error classes, with the evidence pack to go with them.
Read the guideRetry Logic for Failed Payouts with Exponential Backoff and Error Classification
Makes the resolution step concrete, retrying by failure class with stop conditions in place of a blanket re-attempt.
Read the guideHow Platforms Validate Bank Accounts Before Mass Payouts
The prevention half, validating destination details per rail and corridor so the failure is avoided at source.
Read the guideFrequently Asked Questions
What failure types are covered?+
Is this an official return reason?+
How should I use the prevention checklist?+
Can this help with reconciliation?+
Does this cover every bank rail?+
Stop diagnosing one-offs. Fix the return-code problem at the rail
Gruv adds format validation, beneficiary verification, and smart retries to the payout run so the failures this tool surfaced stop re-landing next cycle.
Many teams start with a narrow launch in weeks.