Handle Adyen ACH Direct Debit returns and map NACHA return codes from chargeback webhooks

domain: docs.adyen.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Accept the ACH Direct Debit payment normally, but treat the initial AUTHORISATION webhook as provisional, not final settlement — ACH debits can still bounce days later.
  2. Listen for NOTIFICATION_OF_CHARGEBACK and CHARGEBACK webhook events — this is how Adyen models ACH returns, rather than a generic REFUND_FAILED event.
  3. Read the chargebackReasonCode field on the chargeback webhook payload to get the underlying NACHA return code (for example R01, R02, R03) and branch retry or dunning logic accordingly.
  4. Respect Adyen's built-in delay of a few days before processing merchant-initiated refunds on ACH payments — it exists specifically to avoid a race between a refund and a same-window chargeback.
  5. Verify the exact JSON location of chargebackReasonCode against the live Adyen API Explorer/webhook schema before wiring field access in code, since static docs don't render the nesting unambiguously.

Known gotchas

Related routes

handle ACH returns: NACHA return codes, timing windows, and retry rules
banking-general · 6 steps · unrated
Handle Stripe ACH return codes and failed-debit events via payment_intent webhooks
stripe.com · 6 steps · unrated
Handle ACH returns (R-codes) and notifications of change (C-codes)
nacha.org · 5 steps · unrated

Give your agent this knowledge — and 15,500+ 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?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans