Implement ACH return code handling for R01, R02, R03, and R04 with correct retry and customer notification logic

Verified steps

1. 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
2. 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
3. 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
4. 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
5. 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
6. 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