A reference architecture for B2B ACH payments

This is a reference architecture for discussion and solution design. It is not a claim that the platform has been deployed for a customer, certified, or approved for production. It is not legal, tax, banking, accounting, or compliance advice. Financial regulation and ACH obligations depend on the funds flow, the contracts, the customer type, and the activities performed. Using a payment provider does not remove every duty from the platform operator. Validate the design against current provider documentation, Nacha rules, contracts, and qualified advisors before any live payment.

The problem the blueprint addresses

Businesses often run invoices, bank-payment requests, status updates, exceptions, and reconciliation in separate tools. The result is manual work, late visibility, and a payment that is hard to explain from initiation through settlement or return.

The proposed platform lets a business onboard users with roles, keep customer and invoice records, link a bank account through an approved provider flow, initiate an ACH payment, show a clear status, post a double-entry ledger, and reconcile internal records with the provider. Target users in the reference include small and medium-sized businesses, consulting firms, property and service businesses, B2B vendors, and subscription businesses.

The recommended split is deliberate. The platform owns the business experience, payment orchestration, the internal ledger, monitoring, and reconciliation. An established provider handles the external payment rail under the commercial and compliance arrangement you agree. The platform must record, secure, explain, and reconcile every lifecycle event. It should not assume it is a bank, that it holds customer funds, or that it operates the ACH network.

What a first release includes

The reference MVP covers tenant and user management, customers and invoices, payment links, ACH initiation, bank-linking through a provider-approved flow, status and notifications, webhook intake, ledger entries, basic fees, daily reconciliation, exception reporting, and an administrative view with audited access.

Out of scope at the start: operating an ACH network, holding customer funds or stored-value balances unless that is separately assessed, international remittance, lending, card issuing, crypto, marketplace escrow, and any AI that moves money on its own. Other payment rails wait until the lifecycle, the ledger, reconciliation, risk controls, and support operations are reliable.

A modular monolith for the core domain, plus asynchronous workers for provider calls, webhooks, notifications, and reconciliation, keeps operations simpler while module boundaries stay available for a later split. The reference stack is a web client, a Java and Spring Boot application, PostgreSQL for transactional records, managed containers, queues with dead-letter handling, an OIDC identity provider with MFA, managed secrets and encryption keys, and tracing. Those are recommendations for this blueprint. Provider and bank-linking products are chosen by due diligence, not assumed. Confirm debit and credit support, settlement timing, returns, authorization evidence, webhooks, idempotency, pricing, production approval, and eligibility for the business model.

Payment state

An accepted API call is not settlement. ACH is asynchronous. Map the provider’s real statuses onto an internal machine, for example: created, pending authorization, bank account linked, payment initiated, processing, and then settled, returned, failed, or canceled when the provider and the timing allow it.

Validate every transition against the current state and provider evidence. Keep event evidence under a retention rule. Handle duplicate and out-of-order events. Do not delete a posted financial record to correct a return. Post a compensating entry. Show customers a status that matches an approved provider mapping. Define cancellation cutoffs with the provider and the applicable ACH rules.

For a 2,500 dollar invoice, the application creates its own payment id and may show Processing at first. Only validated provider events and reconciliation rules decide the final outcome. Store the amount as integer minor units, 250000 cents in this example, not as a binary floating-point number.

Integration, APIs, and the ledger

Keep provider-specific logic behind an internal interface. Internal models use platform ids and normalized statuses. The illustrative flow creates or verifies the business with the provider, starts bank linking with a short-lived token from the backend, lets the customer authenticate in the provider’s own experience, exchanges tokens on the server, stores a funding-source reference rather than online-banking credentials, captures ACH authorization evidence, creates an internal payment and an idempotency key, submits the transfer, and then processes events asynchronously.

APIs in the reference are versioned, authorized on every resource, and idempotent on money movement. Creating a customer, an invoice, a bank-link token, a token exchange, a payment, a payment read, a webhook, and a reconciliation view are separate operations with separate controls. The webhook endpoint verifies signatures. Tenant identity comes from the authenticated session, not from an id the client supplies. The backend confirms that the invoice belongs to the tenant, the amount is payable, the funding source is eligible, authorization is complete, and risk controls allow the request.

Core records are tenants and memberships, customers and invoices, funding-source references, payments with a platform id and a provider reference, webhook and payment events with a unique provider event id, a balanced journal, reconciliation runs, and audit events. Every posted journal balances in one currency. Separate receivables, clearing, fees, and returns according to the actual funds flow. Do not assume the platform holds funds or owes a merchant until the contract and the banking model say so. A hypothetical fee on a 2,500 dollar payment changes the net amount, and the journal depends on who charges the fee and who receives the funds. A qualified accountant should review the mapping.

Reliability and reconciliation

Verify a webhook, persist it with a unique event id, acknowledge quickly, and process it on a queue. The worker deduplicates, checks the state transition, updates the payment, and posts the ledger in one transaction. When a business transaction must emit an event, write the business row and an outbox row in the same database transaction, then publish. That avoids committing a payment and losing its event.

Assume at-least-once delivery. Use idempotency keys, bounded backoff, dead-letter alerts, timeouts around provider calls, and a scheduled reconciliation that catches missed webhooks. Carry a correlation id from the API request through the provider call, the webhook, the ledger, and reconciliation.

Daily reconciliation fetches provider and settlement records, matches them on provider reference, platform payment id, amount, currency, and status, and opens an exception for anything missing, duplicated, or mismatched. Corrections go through auditable ledger adjustments. The operational view shows initiated, settled, returned, failed, and pending payments, provider errors, queue depth, unmatched items, return-rate trends, and ledger imbalance checks.

Security, risk, and how you would deliver it

Use TLS, encryption at rest, a secrets manager, MFA for privileged users, least-privilege cloud access, and separate environments. Authorize every data path for the tenant. Redact logs so tokens, bank credentials, and full account numbers never appear. A shared database with a tenant id is a reasonable start when application authorization, constraints, and isolation tests are strict. Row-level security can add depth. It does not replace application checks. Define retention with the provider and with counsel.

Design customer verification, retrievable ACH authorization, transaction limits, velocity checks, and explicit handling for returns, disputes, cancellations, and support. Document who is responsible among the platform operator, the provider, bank partners, and customers. Review the model with payments counsel, security, and accounting before production.

The reference roadmap is about twelve weeks of planning, not a commitment: discovery and funds-flow definition, business workflows, sandbox integration, ledger and reconciliation, then production readiness including a threat model, monitoring, restore exercises, and provider approval. Timing depends on scope, provider onboarding, and the chosen funds flow. A first team in the blueprint is a product owner, a backend payments engineer, a frontend engineer, QA, cloud engineering, and part-time compliance, accounting, and security advisors.

Tests cover state transitions, ledger balance, tenant authorization, idempotency, sandbox integration, duplicate and out-of-order events, returned payments, tenant-isolation attempts, backup restore, and reconciliation recovery.

Where AI fits, later

After processing, the ledger, reconciliation, security, and operations are stable, AI can reduce manual effort: explain a likely cause of an unmatched record, answer a support question from approved status, draft an invoice reminder for a person to send, or flag unusual activity for review. Scoped access, least-privilege tools, human approval for sensitive actions, and an audit from request to outcome are part of that layer. The model must not bypass payment controls or the ledger, and it must not move funds on its own.

Before a build, decide who the payer is, whether the platform initiates debits, credits, or both, the exact funds flow, whether funds are ever held, which provider is eligible, who pays fees, what verification and limits apply, and what recovery objectives the first release actually requires. Validate the business model and the funds flow first. Confirm provider eligibility and compliance duties second. Then freeze the ledger, the API contracts, and the production infrastructure.