Payment troubleshooting

This guide covers: checking ACH status on a payroll, reading a return code, resubmitting after a fix, and when to contact support.

ACH transfers fail. They fail when accounts are closed, when funds aren't available, when account or routing numbers were entered wrong, when the receiving bank rejects for any of two dozen documented reasons. Payrollix surfaces those failures inline on the payroll run that triggered them, gives you the return code from the receiving bank, and routes resubmissions back through the standard pipeline once the underlying issue is fixed.

Check ACH status on a payroll

What it does: Shows whether direct deposits for a specific payroll have been initiated, are in progress, completed, or failed.

Where: Dashboard → Clients → [client] → Payroll → [payroll run] (/clients/{clientId}/payroll/{payrollId}) → Direct Deposit Status card.

Steps:

1. Open the payroll run.
2. Scroll to the Direct Deposit Status card — only visible once the payroll is in completed status.
3. The card shows one of five states:
   • Direct Deposits Not Initiated (yellow) — runs that never had ACH kicked off. Click Process Direct Deposits to start.
   • Pending Funding (yellow) — a Same-Day ACH debit for the supplemental funding amount was kicked off; the row shows the supplemental amount and current debit status.
   • Direct Deposits In Progress (blue) — ACH transfers are being processed; the inline status line shows the current state.
   • Direct Deposits Complete (green) — all ACH transfers settled successfully.
   • Direct Deposit Error (red) — at least one transfer failed; the card shows the message and failed-transfer count.
4. The refresh button (top right of the card) re-queries the latest status from Moov without leaving the page.

Who: Accountant + SUPPORT.

Notes: The card hides for runs that haven't reached completed — drafts and approved-but-not-finalized runs don't have DD records yet. The Same-Day ACH checkbox on the approved-state card decides which speed lane to use; same-day costs extra but lands the same business day.

Read a return code

What it does: Interprets the NACHA return code (R01–R85) that the receiving bank returned with the failed transfer.

Where: Payroll detail page → Direct Deposit Status (red error state) → per-transfer detail.

Steps:

1. On a failed payroll run, the Direct Deposit Status card shows the red error state with the count of failed transfers.
2. Open the per-employee detail (if surfaced) or look in the audit log for the return code and reason text.
3. Common codes:
   • R01 — Insufficient Funds: the receiving account had insufficient funds when the credit posted. Re-attempting later may succeed.
   • R02 — Account Closed: the account has been closed. Get a new account number from the employee.
   • R03 — No Account / Unable to Locate: the routing + account number combination doesn't match a real account. Verify both with the employee.
   • R04 — Invalid Account Number: account number has the wrong format. Re-enter from a voided check or direct-deposit form.
   • R05 — Unauthorized Debit: employee or bank disputes the credit. Confirm authorization.
   • R07 — Authorization Revoked: employee revoked authorization. Switch to paper check until re-authorized.
   • R08 — Payment Stopped: stop-payment was placed. Contact the employee.
   • R09 — Uncollected Funds: held but not yet collected. Retry later.
   • R10 — Customer Advises Not Authorized: similar to R05; treat as unauthorized.
4. Full code reference is in the direct deposit return codes guide.

Notes: The return code is the bank's terse machine reason. The narrative resolution depends on the code — some are retry-friendly (R01, R09), others require account changes (R02, R03, R04), and a few flag authorization issues (R05, R07, R10).

Resubmit after a fix

What it does: Re-runs direct deposit for the payroll once the underlying issue is corrected.

Where: Payroll detail page → Direct Deposit Status card → Process Direct Deposits button.

Steps:

1. Fix the root cause first:
   • R02 / R03 / R04 — update the employee's bank account on the employee detail page (/clients/{clientId}/employees/{employeeId}). Add the corrected routing/account and remove the bad one.
   • R01 / R09 — wait for the bank's hold/funding cycle, no data change needed.
   • R05 / R07 / R10 — confirm authorization or flip the employee to paper check until they re-authorize.
2. Return to the payroll detail page.
3. Click Process Direct Deposits on the Direct Deposit Status card. The button is enabled when the status is not_initiated or error.
4. Tick the Same-Day ACH checkbox if you need the money landed today (extra fee). Otherwise standard ACH ships at the next batch window.
5. Confirm. The card flips to In Progress.

Who: Accountant + SUPPORT (process); ADMIN for special recovery flows.

Notes: Resubmission re-attempts only the failed employees, not the ones that already cleared. Successful transfers from the first run are not double-debited. If the bank record on the employee was changed since the original run, the resubmission uses the new record.

Funding (company-side) failures

If the company bank debit fails (the wallet didn't have enough cleared funds at credit time), the page shows the Pending Funding state with a Same-Day ACH debit in flight. This is the supplemental pull-from-client-bank path. The debit status (pending / completed / failed) sits in the card. If the supplemental debit itself fails, you get a separate error and need to fix the company bank — see Company bank account setup.

For company-bank debit reject scenarios, an accountant payment-failure alert fires automatically — only on client-bank money-movement failures (funding debit, returned DD, client_debit voucher reject), not on filing or wallet-push errors.

When to contact support

Most ACH return cases are self-serve through the steps above. Escalate to support when:

• A transfer is stuck in submitted for more than two business days (standard ACH) or one business day (same-day) without a return code. Moov may have a webhook delivery issue.
• You see Direct Deposit Error with a status message that isn't a NACHA return code (network errors, Moov 5xx, etc.).
• The supplemental funding debit (the Same-Day pull from client bank) fails repeatedly with R01 — funding is genuinely short and you need admin help with force_fund from the admin payroll-remediation tool.
• A return came back with R05 / R07 / R10 (authorization issue) and the employee disputes it — support can review the audit trail and notification log.
• The Moov account itself shows a capability as rejected or requested on the Banking page — onboarding may need re-running before any further transfers go through.

When you escalate, include the payroll ID, the affected employee IDs (or "company funding debit"), the return code(s), and the Moov transfer IDs from the audit log. Support uses those to pull the full Moov transfer trace.

---

Related: Direct deposit return codes · How ACH timing works · Company bank account setup · Employee direct deposit.