Skip to content

BOOK

BOOK transfers move funds between two accounts at GIB: core to core, virtual to core, or virtual to virtual. They settle on GIB's internal ledger without touching the Federal Reserve, so they're faster, cheaper, and cannot return.

If both endpoints are at GIB, BOOK is almost always the right rail.

When to use it

  • Transfers between end users within your platform
  • Sweeping funds between a virtual account and the parent core / FBO account
  • Internal accounting transfers (operations to reserves, reserves to revenue)
  • Two-leg flows where ACH would introduce return risk on a leg that's logically internal

Don't use BOOK if either endpoint is at an external bank, use ACH, Wire, or ICL depending on the use case.

Operations

Operation Description API reference
Create BOOK transaction (subledger) Submit a single internal transfer (type: "book") using two subclient_account IDs createTransaction
Parse BOOK file Validate a BOOK file or JSON payload without creating Transactions publicTransactionParseBOOK
Create BOOK transactions (file) Submit a file or JSON payload to create Transactions synchronously transactionCreateBOOK
Create BOOK transactions (bulk) Submit a large file asynchronously; returns immediately, processes in background transactionCreateBOOKBulk
List transactions Retrieve and filter BOOK Transactions getTransactions
Get transaction history Retrieve audit history getTransactionHistory

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

BOOK files must be balanced

A BOOK file uses the ACH file format, but it balances differently from an ACH file. Each transfer is a pair of entries: a credit (push) to the receiving account and a debit (pull) from the sending account, for the same amount. Every credit in the file needs its matching debit.

  • No offset records. ACH files can carry an offset entry that balances a batch. BOOK files cannot; a file with one is rejected.
  • Pairs are matched by amount. If two pairs in a file have the same amount, give both entries of each pair the same short label in the Addenda 05 paymentRelatedInformation field, so GIB knows which credit goes with which debit.

A transfer created with createTransaction builds the pair for you.

Lifecycle

BOOK follows the standard Transaction state machine.

Timing & cutoffs

For BOOK processing windows and submission behavior outside the window, see the central Timing & cutoffs.

Failure modes

Failure Result
Insufficient funds at origin HTTP 402 PaymentRequired; transaction failed. If overdraft rejection is enabled, all transfers in the same batch reject together.
Origin or destination frozen HTTP 403 ForbiddenError; transaction failed
Origin or destination closed / unknown HTTP 404 NotFoundError; transaction failed
OFAC hit on a counterparty Subclient Rejected at submission (403 ForbiddenError)
Inactive virtual account on either side See Automated Returns → Inactive Virtual Account

For the complete failure-mode reference, see Errors.

Idempotency

Always populate the external_key field in the request body on BOOK creation. BOOK transfers between the same accounts for the same amount within a short window are flagged as duplicates by duplicate detection; a unique external_key per logical operation distinguishes a legitimate retry from an accidental duplicate. See Idempotency.

Notifications

You receive a webhook on each state transition (outbound_book_transaction_* / inbound_book_transaction_*).