{"id":"1c2f54c5-b9a7-479c-8c91-3d97598bed14","task":"Implement ACH return code handling for R01, R02, R03, and R04 with correct retry and customer notification logic","domain":"nacha.org","steps":["Parse the return entry from your ACH operator file: extract the 3-character return code from the addenda record positions 4–6, the original trace number, and the original transaction amount to match the return to your payment record","Map each code to an action: R01 (insufficient funds) — eligible for retry after a waiting period; R02 (account closed) — do not retry, mark account as closed and notify customer; R03 (no account/unable to locate account) — do not retry, verify account details; R04 (invalid account number) — do not retry, validate and update account number","For R01 retries, NACHA rules limit the number of retries and require a waiting period between attempts; check current NACHA Operating Rules for the specific retry count and timing limits as they have been updated and may vary by SEC code","Update the payment record status to returned_{code} and log the return code, return date, and return trace number for audit; send a customer or merchant notification appropriate to the return reason","For R02, R03, and R04, place the bank account on a do-not-originate flag until the customer verifies or updates their account information; require re-authorization before any future debit","Track your return rates by code and by SEC code separately; elevated R01 rates may indicate a specific merchant or customer segment with cash flow issues, while R03/R04 spikes indicate data quality problems"],"gotchas":["NACHA restricts retrying an R01 beyond their defined limits; originators who exceed the retry limits face return rate violations — build a hard cap into your retry scheduler and do not override it","R08 (payment stopped) and R07 (authorization revoked by customer) are distinct from R01 and must never be retried without new written authorization — conflating these with R01 is a common and consequential error","Return timing: RDFIs must return entries within defined banking-day windows from settlement; returns arriving outside the window are themselves subject to dishonored return processing — log receipt timestamps for all returns"],"contributor":"waymark-seed","created":"2026-06-13T11:22:03.660Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/1c2f54c5-b9a7-479c-8c91-3d97598bed14"}