ACH overview

The bank originates ACH credits and debits, sends them to the ACH operator in NACHA files, and receives entries from other banks as the RDFI. The operator on the other side is a simulator today.

The objects

Object	What it is
ACH Transfer	One credit or debit the bank originates. Ids start `acht_`.
International Transfer	The same entry in the IAT class, with the foreign parties at the top level. See International ACH (IAT).
ACH Originator	The bank's record of a customer that originates: the company identification on its batches, the classes it may use, whether it must prenote, and its limits. A limit of zero is no limit. Ids start `acho_`.
ACH Change	A notification of change, received about an entry the bank originated or sent about one it received. Ids start `achc_`.
ACH Receipt	The outcome of one entry the bank received. Ids start `achr_`.
ACH file	A NACHA file the bank sent or received, read through the Rail endpoints. Ids start `achf_`.
ACH Return Rate Evaluation	The daily measure of an originator's debit returns against the Nacha thresholds.

Originating a transfer

POST /transfers/ach takes a TransferRequest. The Idempotency-Key header is required. A repeat with the same key answers 200 with the transfer made the first time, and no second hold is placed.

account_idstringRequired

The account the entry is for. It must be open.

directionstringRequired

credit sends money from the account to the counterparty. debit pulls money from the counterparty into the account.

amountintegerRequired

Minor units. Positive and at most 9999999999; zero only on a prenotification.

currency_codestringRequired

Must be the account's currency.

counterpartyobjectRequired

The other side: routing_number (nine digits, check digit verified), account_number (at most 17 characters), name, and account_type, which is checking or savings.

sec_codestringRequired

PPD, CCD or IAT. See Entry types.

descriptionstringRequired

At most 10 characters, the length of the NACHA company entry description. Stored in upper case.

effective_datestring · dateOptional

The banking day the entry should settle. See Timing.

same_daybooleanOptional

Settle today in the next Same Day ACH window.

prenotebooleanOptional

A zero-dollar prenotification. See Changes and prenotes.

iatobjectOptional

The international addenda. Required when sec_code is IAT and refused otherwise.

What the bank does with it

The fields are checked. A routing number that fails its check digit answers payments.invalid_routing_number.
The effective date is set.
The customer's ACH Originator is found, or created with the bank's default limits on the first origination. A suspended originator answers payments.originator_suspended, and a class it may not use payments.unsupported_sec_code.
A notification of change already received about the same counterparty account is applied, and change_id names it.
The entry is counted against the originator's limits. One that would pass them answers payments.exposure_limit_exceeded.
On a credit, the account's payment limits are checked, then a pending_debit hold for the amount goes on the account and hold_id names it. An amount above the available balance answers ledger.insufficient_available.
The counterparty's name goes through sanctions screening. A result other than clear stores the transfer as held_for_review. A credit that clears is then judged by the fraud rules, which can hold it the same way.

The answer is 201 with the ACH Transfer, pending or held_for_review. States and notifications follows it from there.

A token obtained from a customer API key cannot call this route; the answer is payments.approval_required. An API key pays by ACH through a scheduled transfer that a person approves. The same code answers a credit that falls under the account's approval policy.

Credits and debits

direction is read from the account's side. A credit is held at once. When its file settles, the bank debits the account, credits its Federal Reserve cash account in the ledger, and releases the hold in the same journal. A debit holds nothing. At settlement the bank debits its Federal Reserve cash account and credits the customer's account. A return reverses either posting.

Files and settlement

A pending transfer waits for a file. Bank operations batch the pending entries for an effective date with POST /rails/ach/files: one batch for each SEC code and company identification, and each entry gets its trace_number and file_id. The operator's settlement is posted at POST /rails/ach/files/{id}/settle. These endpoints are bound to bank staff, the operations service or the FedACH connector; a customer's token cannot call them. In a sandbox, POST /simulate/transfers/ach/settle with a file_id plays the operator.

Incoming entries

The FedACH connector delivers each NACHA file addressed to the bank to POST /rails/ach/inbound. Every entry becomes an ACH Receipt with an outcome: posted, returned, accepted (a prenotification), held (a credit waiting for review on the bank's transit account) or blocked. A credit posts at once and is available the next banking day. Entries that cannot post go back to the ODFI in a return file built in the same call. In a sandbox, POST /simulate/transfers/ach/receive delivers a one-entry file through the operator simulator.

Reading transfers

GET /transfers/ach/{id} reads one transfer. GET /transfers with type=ach lists originated and received entries together; a received entry shows its outcome as status. type=iat lists international transfers.