Bank APIs still sit on operating rules
JSON can simplify initiation, but ACH and bank-transfer products still depend on participating institutions, approved use cases, authorization, submission windows, settlement, returns, and account data controls. Start by identifying the originator, processor or third-party role, sponsoring financial institution, receiver, and the accounts used for settlement.
Configure routes on the server. A payroll credit, vendor payment, consumer debit, bill payment, and account-funding transaction are not interchangeable uses of a generic transfer endpoint. The route profile should define direction, customer type, required authorization, schedule, limits, data, and return handling.
Model payments independently of bank files
The public resource should hold a payment identifier, amount, direction, purpose, receiver type, tokenized account, requested date, authorization reference, route profile, and state. A rendering layer can group approved payments into bank files or messages. This separation makes it possible to change processors without changing the merchant contract.
Preserve the normalized input, rendered artifact digest, control totals, delivery acknowledgement, trace references, and bank reports. If transport fails after transmission, determine whether the bank received the submission before sending again. Client idempotency does not by itself prevent duplicate bank entries.
Make schedules and availability explicit
Return the requested effective date, calculated submission window, bank acceptance, expected settlement, and availability policy as distinct fields. Account for business days, holidays, cutoffs, same-day eligibility, prefunding, and customer-specific lead times. A timestamp without banking context is not enough.
Direct deposit and payroll often need stronger approval controls and earlier deadlines. Separate the person who prepares instructions from the person who approves a batch when the organization requires dual control. Alert administrators to account changes close to a payroll cutoff.
Protect account data and authorizations
Tokenize routing and account details. Show masked values in routine interfaces and limit access to the service that submits payments. Account validation can reduce errors, but it does not replace authorization or guarantee a future debit. Store the validation method, result, time, and source.
For debit use cases, preserve the authorization artifact, terms version, channel, date, and revocation state. For credits, treat destination changes as high-risk actions. Use step-up review, out-of-band confirmation where appropriate, and audit records for every administrator action.
Handle returns and changes as product events
A return reason can determine whether an account should be disabled, whether a retry is permitted, whether a balance must be reversed, and what the customer must do next. Store the original bank code and map it to a normalized category without losing detail. A payment can settle and later return, so ledger availability must reflect the product's exposure policy.
Notifications of change and corrected account information need their own case workflow. Do not silently rewrite a tokenized destination based on an inbound notice. Review, communicate, and version the account so historical payments remain tied to the data used at submission.
Design direct deposit and bill pay separately
Direct deposit is an outbound credit product with receiver onboarding, destination verification, scheduling, and sensitive change controls. Bill pay can involve an account-to-account debit, a credit to a biller, a check-like fallback, or a card-funded route. The API should expose the actual method and expected lifecycle rather than labeling every product “bill pay.”
For recurring obligations, store the mandate or schedule independently of each payment. Generate a new payment instance for every occurrence, with its own idempotency, state, ledger entries, and settlement evidence.
Reconcile at payment, batch, and account levels
Batch totals can match while individual entries are wrong. Match trace references and amounts where possible, then reconcile aggregate control totals and bank statement activity. Differences enter suspense with an owner and age. Corrections are linked adjustment entries, not edits to settled history.
Operational metrics should include submission success, bank acceptance, settlement delay, return rate by reason, account-change alerts, duplicate prevention, and aged reconciliation breaks. The system is complete only when finance and support can operate it alongside the API.
