Batches & Files¶

A Batch is a grouping of one or more Transactions submitted through a single payment-initiation process. Every Transaction belongs to exactly one Batch, even a one-off Transaction is wrapped in a Batch of size one. Batches matter because they define the unit of submission, the unit of cancellation, the unit your reconciliation often references, and the layer at which file formats and submission workflows are defined.

This page covers both the conceptual model (what a Batch is, the lifecycle, the fields) and the operational mechanics (how files are submitted, the four workflow patterns, file formats per rail). The Batches API covers listing, export, updating mutable fields, retrieving associated files, and audit history; cancel a Batch via updateBatch with state=canceled (only while in created). For Transaction creation from your subledger, see createTransaction.

Why batches exist¶

Three reasons:

• NACHA expects them. ACH files are batches by design: BatchHeader and BatchControl records wrap the entries, with shared metadata like companyName and companyEntryDescription applied across all entries in the batch.
• Atomic submission. Submitting many Transactions as one Batch makes the file atomic from a parsing perspective: either the file is accepted in full or rejected, with per-Transaction failures handled inside.
• Cancellation granularity. Canceling a Batch cancels all child Transactions still in pending_settlement or created state. This is useful when you need to abort a payment run before processing begins.

Lifecycle¶

Batches progress through a state machine reflected by the state field. Batches use these states (a subset of the Transaction states; Batches do not have pending_settlement):

1. created: the initial state upon successful creation
2. processing: the Batch is actively being processed
3. under_review: under review and might take longer to be processed, or might fail
4. processed: the semi-terminal state for successfully processed items
5. posted: the terminal state when every Transaction in the Batch is posted
6. failed: an errored state, indicating the Batch could not be completed
7. canceled: the user (or in rare cases the bank) canceled before processing

Allowed transitions¶

Start state: created

created → processing → ...
created → under_review → ...
created → processed → ...
created → failed
created → canceled

processing → under_review → ...
processing → processed → ...
processing → failed

under_review → processing → ...
under_review → processed → ...
under_review → failed

processed → posted
processed → failed

Final states: posted, failed, canceled

Child Transactions follow a similar state machine but additionally support a pending_settlement state. See Transactions → Lifecycle.

Cancellation rule: canceled is in general set by the client, but can also be set by the bank. It is only possible to cancel a Batch in state created. Once a Batch enters processing, cancellation is no longer possible; reverse via a new opposite-direction Transaction (for BOOK) or via Returns where applicable.

A Batch's state derives from its Transactions: a Batch is posted only when every Transaction in it is posted; a Batch can be processed while individual Transactions are still settling.

Fields¶

Submission workflows¶

GIB exposes four submission patterns. Each rail supports the workflows that make sense for that rail:

1. Direct processing¶

• Endpoint: file/create
• Behavior: File parsing, transaction creation, and processing all happen synchronously in the same request.
• Use case: Small files where you need immediate confirmation and the entire operation can complete inside the 30-second request window.
• Cancellation window: None after submission.

2. Delayed asynchronous processing¶

• Endpoint: file/create with the delayed=true parameter
• Behavior: File parsing and transaction creation are synchronous. Processing waits for a pre-configured delay, then runs asynchronously.
• Use case: When immediate processing isn't critical and you want a cancellation window between submission and Fed/network handoff.
• Cancellation window: During the delay; the Transaction can be set to canceled while in created state.
• Note: Company-level setting; ask your GIB onboarding contact to enable.

3. Bulk processing (direct)¶

• Endpoint: file/create-bulk
• Behavior: File parsing is synchronous (the API returns once it's parsed and validated). Transaction creation and processing happen asynchronously in the background.
• Use case: Large files (thousands of entries) where parse-and-validate is fast but processing each entry would exceed the 30-second window.
• Cancellation window: None, processing begins as soon as parsing completes.

4. Bulk processing (delayed)¶

• Endpoint: file/create-bulk with the delayed=true parameter
• Behavior: Parsing synchronous; transaction creation and processing both async with a configurable delay.
• Use case: Maximum flexibility for large batches, large file, plus a cancellation window before processing.
• Cancellation window: Until processing begins.
• Note: Company-level setting; ask your GIB onboarding contact to enable.

Choosing a workflow¶

File formats per rail¶

Different rails accept different file formats. JSON submission is universal; binary file submission is rail-specific:

For ACH, see ACH → Submission paths for the file-vs-JSON tradeoffs.

Balanced files¶

Some rails require every file to be balanced: the file carries the entries that move money into and out of GIB accounts, not only the payments themselves. Each rail balances its own way:

The rail page has the details. Requests to createTransaction are balanced for you.

Duplicate detection at the Batch level¶

Always include an external_key in the request body for every batch/transaction creation call. Without one, retrying a request that timed out can produce a duplicate Batch, and reconciling duplicates of, say, a 5,000-Transaction payroll file is operationally expensive. The same external_key for the same user returns 409 ConflictError on re-submission. See Idempotency.

Failure modes¶

Related concepts¶

• Transactions, the per-entry records inside a Batch
• Idempotency
• Webhooks, state-change events for the Transactions in a Batch
• Reconciliation, references Batches as a unit
• Errors, error response shape
• ACH, ICL, rail-specific file formats