ACH¶

ACH is the primary method of transferring funds in the U.S., and it supports an immense range of payment scenarios. Most payment engines wrap that complexity behind a simpler interface, useful until you need a less-common flow. GIB takes the opposite approach: direct access to the network, with guidance where it helps and no abstraction that hides what's happening. Raw ACH file downloads are always available.

GIB acts as the Originating Depository Financial Institution (ODFI) when you submit; we receive as the RDFI when entries arrive at one of your accounts or virtual accounts.

How ACH works¶

ACH is an asynchronous network that sends files containing batches of transfers from the originating depository financial institutions (ODFI) to the Federal Reserve, and ultimately onward to the receiving depository financial institutions (RDFI). The network is unique in that it enables both push and pull transfers.

When you submit an ACH, those transfers go through multiple state transitions. One of the most powerful features of GIB is our ability to notify you during each transition. This keeps you updated throughout the process and allows you to track the outcome of each transfer.

Those new to payments or the U.S. market are often surprised to learn that ACH does not offer an explicit acknowledgement of success. ACH takes an exception-based approach: you find out the payment is successful by not receiving an error. Such "errors" are called Returns.

When to use it¶

• Push payments (you send money out): payroll, marketplace payouts, vendor payments, refunds.
• Pull payments (you debit an external account): account funding, recurring subscription billing, invoice collection.
• B2B with structured remittance: see CTX in the SEC code table below.

Don't use ACH for:

• Internal transfers between two GIB accounts, use BOOK instead.
• High-value transfers needing settlement finality, use Domestic Wire.
• Cross-border, use International Wire.
• Sub-real-time consumer push, ACH is not real-time even at same-day; use a wire if you need T+0 finality.

Bundling many end-customer payments¶

Fintechs that nest many small end-customer payments inside a single ACH credit (common for consumer remittance routed through a US-based liquidity provider or payment service provider, payroll bulk credits, and marketplace mass payouts) create a Subtransaction for each underlying customer payment, inbound or outbound. The bulk ACH is the only event on the rail; the Subtransactions are how the true senders and ultimate beneficiaries reach GIB's recordkeeping, monitoring, and OFAC screening. For International ACH (IAT), the same applies whenever the IAT batch represents many underlying consumer payments rather than one organization-to-organization transfer.

Operations¶

Transactions cannot be canceled individually; cancel the parent Batch via updateBatch (set state to canceled) while it is in created state.

ACH files must be balanced¶

Every batch you send must be balanced. Each payment entry moves money to or from someone else's account; the batch also carries an offset entry against your own account at GIB, for the net of those entries. The offset is how GIB knows which of your accounts funds or receives the batch: the API uses it as the origin account for every entry in the batch. An offset entry is an entry whose receiver name is OFFSET.

GIB rejects the whole file when you submit it if any batch breaks these rules:

• Use your own account. The offset's routing and account number must be an account at GIB configured on your user.
• One offset per batch. In the JSON format, add an offset object to each batch and GIB generates the offset entry for you. See Create an ACH Transaction using JSON for an example. A batch that mixes debits and credits gets two offset entries from the offset object, one per side. In a NACHA file, a batch may likewise carry at most one debit and one credit offset entry, both on the same account.
• At least one payment entry. A batch made only of offset entries is rejected.
• Balanced amounts. The batch's debits, offset entries included, must equal its credits.
• Rebalance after any change. If you remove entries from a batch, for example after an OFAC rejection, adjust the offset to the remaining entries.

Requests to createTransaction are balanced for you.

Common stages in the lifecycle of an ACH transfer¶

For the canonical state machine, see Transactions.

Initiation¶

Each created ACH transfer request incorporates mandatory details: account number, routing number, amount, and Standard Entry Class (SEC) code. The request may optionally include parameters such as the recipient's name and identifying number, though most financial institutions do not enforce that the recipient name on the transfer match the account holder name.

Batching¶

ACH transactions are batched and do not settle instantly. We acknowledge that this may be a confusing concept in a 24/7 world. As such, when initiating an ACH transfer request, we, as the originating depository financial institution (ODFI), consolidate all ACH transfers into a smaller set of NACHA files for submission.

Submission and clearing¶

Banks submit these batch files to the Federal Reserve at specified times each day. These times align with specific submission windows and affect when funds are available at the receiving depository financial institutions (RDFI). If a file is successfully submitted, the Federal Reserve will respond with an acknowledgment, and GIB publishes and creates webhooks with the submission status of every ACH file.

ACH transfers can be submitted with different settlement timing (Same Day or Standard). For specific cutoffs and processing windows, see the central Timing & cutoffs.

Funds transfer and funds availability¶

The actual transfer of funds occurs during the settlement process, during which the Federal Reserve finalizes their calculations on the amounts to be debited and credited to the bank.

For an outbound ACH credit entry (ACH push from your account at GIB), funds will be deducted from the originator's bank account immediately upon initiation. If there are insufficient funds on the originator's bank account, the transfer request will fail.

For an outbound ACH debit transfer (ACH pull initiated from your account at GIB), funds will be made available upon receipt, subject to any holds placed by the Bank.

For specific timing and availability details, see the central Timing & cutoffs.

Receiving ACH: identifying the sender¶

When an ACH entry arrives at one of your accounts or virtual accounts, the sender is identified by the fields below. A domestic ACH entry carries the receiver's account number only; the NACHA format has no field for the sender's account number.

Company Name is limited to 16 characters, so longer names arrive shortened. When a payment is sent through a payment processor or payroll provider, Company Name and Company Identification may identify that service rather than the payer.

Reconciling by sender. Company Identification paired with the Originating DFI routing number is the most stable way to recognize a repeat sender. Company Identification is assigned by the sender's bank, so it is unique only within that bank.

Identifying payers by account. To tell payers apart reliably, give each payer its own virtual account. The account that receives the payment then identifies who paid.

Getting the full entry. Every field received from the network is available with getTransactionFiles. In the dashboard, open the transaction under Transactions and select Show files. Both offer the raw NACHA file and a parsed JSON version. For full field definitions, see the NACHA ACH Developer Guide.

Returns¶

Returns occur when a payment instruction fails. There are a myriad of reasons why the payment might fail, and fortunately the reason is nearly always provided through the Return Code. You can see the list of Return Codes in the response section here.

Long-tail risk on consumer-authorization codes. Most ACH returns arrive within 2 banking days of the original entry. Codes related to consumer authorization (R05, R07, R10, R11, R37, R38, R51) can arrive up to 60 calendar days after the entry. The original entry will appear settled for weeks; the return can still hit months later. Build your customer-facing fund-availability promises, credit decisioning, and customer support flows accordingly.

Customers are right to be concerned about returns given that they may have already credited the beneficiary and recovery may be difficult to impossible. Note however that ACH push is generally the simpler approach as you are sending money from an account you control, meaning that, assuming you have funds, the most likely return reason relates to having incorrect account details for the beneficiary.

ACH pull is far more likely to result in failure and often occurs due to insufficient funds or invalid account details. Reducing the likelihood of returns is a complex topic. As such, if your funds flow relies upon ACH pulls, we suggest at minimum that you verify the counterparty using micro-deposits or a service like Plaid.

Please also review our Automated Returns documentation. For originating a return on an inbound entry yourself, see Returns.

Return codes¶

The following table covers the supported subset of ACH return codes for use with createTransactionReturn. Codes outside this list will be rejected.

Notifications of Change (NOC)¶

A Notification of Change is a non-monetary message sent by the receiving bank (RDFI) to notify GIB, as the originating bank (ODFI), that information used in a prior ACH entry is incorrect or outdated and should be corrected for future entries. Common corrections: routing number, account number, account type (checking vs. savings), individual name, individual identification number. NOCs frequently result from bank mergers or acquisitions that change routing or account numbers, but they also arise from routine data corrections by the RDFI.

NOCs are not optional to act on. Under the NACHA Operating Rules, your organization must update its records so that future ACH entries to the same receiver use the corrected information within six banking days of receipt of the NOC, or before initiating another entry to that receiver, whichever is later. Non-compliance can result in penalties under the NACHA Operating Rules, and continued non-compliance can lead to the RDFI refusing future entries to the affected receiver.

An NOC itself is informational, not a Return. The original entry was or will be processed normally; the NOC just tells you what to correct going forward.

You'll receive each NOC via webhook when it's posted to the API. Individual users can also opt in to in-app and email notifications via the GIB platform. The corrected information from the RDFI is included in the NOC payload.

Operational notes¶

A few GIB-specific behaviors to be aware of when integrating against ACH:

• ACH origination confirmation. GIB confirms ACH origination via webhook.
• OFAC handling on outbound batches. For OFAC hits, the entire ACH batch is rejected and the customer is notified. The customer must then remove the OFAC-hit transactions and rebalance the ACH file.
• Addenda passthrough. Generally, neither GIB nor our correspondent bank changes addenda content in ACH files. Confirm passthrough of any required data during the penny-test phase to ensure your customer's needs are met.
• Inbound files. Files are pushed to GIB throughout the day, and ACH returns received from RDFIs arrive in them. See Receiving ACH for the sender fields and for downloading the raw and parsed files.

Timing & cutoffs¶

GIB's ACH submission cutoffs, Federal Reserve processing windows, business-day rules, and inbound/return file timing are documented centrally on the Timing & cutoffs page.

SEC codes¶

A Standard Entry Class (SEC) code is a three-character code used to identify various properties of ACH transfers. GIB supports all SEC codes for inbound ACH transfers. However, for outbound ACH transfers initiated via our ACH transfer API, only certain SEC codes are supported by GIB. Be sure to include an entry_class_code when creating an ACH transfer.

NACHA return-rate thresholds¶

NACHA enforces aggregate return-rate thresholds at the program level:

• Administrative (R02, R03, R04, etc.): 3.0%
• Unauthorized (R05, R07, R10, R11, R29, R37, R38, R51): 0.5%
• Total: 15%

Approaching any threshold is an operational issue; GIB monitors program-wide rates and will alert you well before NACHA does. See Reconciliation for daily monitoring practices.

Submission paths: file vs. JSON¶

You can submit ACH in two formats:

• NACHA file: a binary file conforming to the NACHA spec (PPD, CCD, CTX, etc.). Best for batch use cases or when migrating from an existing in-house ACH stack. See Batches & Files.
• JSON: a structured request body. Best for one-off submissions, API-first integrations, and when you don't already have a NACHA file generator.

Both paths produce identical results downstream; pick whichever fits your stack.

Related concepts¶

• Transactions, data model and full state machine
• Batches & Files, submission workflows
• Automated Returns, when GIB returns inbound entries on your behalf
• Returns, originating returns
• Reconciliation, daily reconciliation when using virtual accounts
• Webhooks, transaction.ach.* event delivery
• Idempotency, safe retries on POST
• Errors, error response shape and code catalog