Handle Plaid Transfer (ACH) return events and update transfer status in response to return codes
domain: plaid.com/docs/transfer · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Set up a Plaid webhook endpoint and subscribe to TRANSFER_EVENTS_UPDATE notifications
When a TRANSFER_EVENTS_UPDATE event arrives, call the transfer/event/sync endpoint to retrieve pending events in order
Inspect each event for event_type of returned and read the return_code field (e.g., R01 insufficient funds, R02 account closed, R10 unauthorized)
Update your internal payment record status to returned and record the return code and timestamp
For R01 returns, apply your retry policy (delay and retry once for temporary insufficiency); for R02 and R10, mark the account as invalid and require customer re-verification
For R10 unauthorized returns, follow NACHA regulations by ceasing all debit attempts on that account until re-authorization is obtained
Known gotchas
ACH return windows vary: administrative returns (R02–R09) must come back within 2 banking days, while consumer unauthorized returns (R10) have a 60-calendar-day window
Plaid's transfer/event/sync cursor is stateful per client; if you lose the cursor state, you must re-fetch from offset zero and deduplicate events
Excessive R01 and R10 return rates above NACHA thresholds can trigger originator monitoring or suspension; track your return rate per SEC code
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?