How do I set up ACH payments API workflows for recurring invoicing and return handling?

Here’s a practical way to set up ACH payments API workflows for recurring invoicing and return handling.

---

1) Core ACH workflow pieces

You generally need these building blocks:

• Customer bank account collection
• Bank account verification
• Mandate / authorization capture
• Payment initiation
• Invoice linkage
• Return / NSF handling
• Retry / dunning logic
• Reconciliation and reporting

ACH is not instant, so your workflow should be built around asynchronous states.

---

2) Recurring invoicing workflow

A. Collect and verify bank details

At onboarding:

1. Collect bank account info securely
2. Verify the account
   • Instant verification via bank login/aggregation, or
   • Micro-deposits, or
   • Processor-provided verification
3. Store a tokenized payment method, not raw bank data

B. Capture authorization

Before charging ACH, make sure you have a valid authorization:

• Customer agreement text
• Date/time accepted
• IP / metadata if needed
• Payment frequency and amount rules
• Cancellation terms

Store this with the customer profile because it may be needed for disputes.

C. Create invoice schedule

For recurring billing:

• Generate invoices on a schedule
• Attach the ACH payment method as the default payment source
• Set due date and grace period
• Define retry logic for failed payments

D. Submit ACH debit

When an invoice becomes due:

1. Create payment intent / ACH debit
2. Mark invoice as processing
3. Submit to ACH network through your provider
4. Wait for settlement / final result

Typical states:

• pending
• submitted
• settled
• failed
• returned

E. Reconcile invoice and payment

When the debit settles:

• Mark invoice paid
• Record settlement date
• Save transaction ID / trace number
• Update customer balance

---

3) Recommended event-driven architecture

Use webhooks or callbacks from your payments provider.

Example events to handle

• payment.created
• payment.submitted
• payment.settled
• payment.failed
• payment.returned
• customer.bank_account.verified
• invoice.paid

Internal state machine

A simple pattern:

• Invoice created
• Payment initiated
• Await network result
• If settled → close invoice
• If returned → reopen invoice and start recovery flow

---

4) Return handling workflow

ACH returns can happen for many reasons:

• Insufficient funds
• Invalid account
• Unauthorized debit
• Account closed
• Stop payment
• Duplicate entry

A. Capture return data

When a return happens, store:

• Return code
• Return reason
• Return date
• Original transaction ID
• Amount
• Customer/account reference

B. Classify the return

Split returns into:

• Retryable: NSF, temporary issue
• Non-retryable: closed account, unauthorized, stop payment

C. Decide next action

For retryable returns:

• Notify customer
• Retry after X days
• Offer alternate payment method

For non-retryable returns:

• Suspend ACH attempts
• Request new bank account
• Escalate to collections if needed

D. Update invoice status

A returned payment usually means the invoice is not truly paid.

Possible handling:

• Change invoice back to open
• Add return fee if allowed and disclosed
• Log the return against the customer ledger

---

5) Retry strategy for recurring ACH

ACH retries should be conservative.

Suggested pattern:

• Retry only on eligible return codes
• Wait a few days between retries
• Limit attempts, for example 2–3 total
• Avoid repeated retries on unauthorized or closed accounts

Example:

• Day 0: debit submitted
• Day 2: return received NSF
• Day 5: retry once
• Day 8: final retry or move to alternate method

---

6) Suggested database objects

Customer

• customer_id
• name
• email
• ach_authorization_status

Bank account

• bank_account_id
• customer_id
• token
• last4
• routing_last4
• verified_status
• active

Invoice

• invoice_id
• customer_id
• amount
• status
• due_date
• paid_at

ACH payment

• payment_id
• invoice_id
• bank_account_id
• amount
• status
• trace_number
• submitted_at
• settled_at

Return record

• return_id
• payment_id
• return_code
• return_reason
• received_at

---

7) API endpoints you may want

A typical REST design might include:

• POST /customers
• POST /customers/{id}/bank-accounts
• POST /bank-accounts/{id}/verify
• POST /subscriptions
• POST /invoices
• POST /invoices/{id}/collect
• POST /payments/ach
• GET /payments/{id}
• POST /webhooks/ach

---

8) Example flow

Recurring invoice payment

1. Customer signs up and adds bank account
2. You verify the account
3. Customer authorizes recurring ACH debits
4. Monthly invoice is generated
5. Payment request is submitted
6. Provider confirms settlement
7. Invoice marked paid

Return handling

1. ACH debit returns NSF
2. Webhook receives return event
3. Invoice marked unpaid again
4. Customer notified
5. Retry scheduled or alternate method requested

---

9) Important compliance and operational considerations

• Use a PCI-like secure posture even though ACH is not card data
• Store only tokenized bank details if possible
• Keep authorization evidence
• Respect NACHA rules and return windows
• Implement idempotency keys for payment creation
• Log all state transitions
• Protect against duplicate debits
• Have clear customer notifications for retries and returns

---

10) Best-practice implementation pattern

If you’re building this yourself or integrating a processor:

Use:

• Idempotent payment creation
• Webhook-driven updates
• State machine for each payment
• Separate invoice and payment records
• Return-code-based decision logic

Avoid:

• Assuming ACH is paid immediately
• Auto-retrying every failure
• Marking invoices paid before settlement
• Reusing raw bank details in multiple systems

---

11) Minimal workflow summary

1. Collect and verify bank account
2. Capture ACH authorization
3. Generate recurring invoice
4. Create ACH debit on due date
5. Wait for settlement webhook
6. If settled: mark invoice paid
7. If returned: reopen invoice, classify return, retry or escalate

---

If you want, I can also provide:

• a sample ACH payments API design
• a webhook event schema
• a state machine diagram
• or a code example in Node.js, Python, or Ruby.