Skip to content

Transactions

A Transaction is the fundamental record of money movement on the GIB platform. Every push, pull, deposit, transfer, return, and reversal is a Transaction. Transactions are grouped into Batches, assigned to a User, and ride one of the supported rails. The full Transactions API surface covers filtering, export, submission from your subledger, origination of returns, and history retrieval.

Understanding the Transaction state machine is essential, it's the same machine across every rail, and every webhook event is a state transition on a Transaction.

Transaction types

The type field identifies the rail:

Type Rail Page
ach ACH ACH
book BOOK (internal) BOOK
wire Domestic wire (legacy / Fedwire) Domestic Wire
wire20022 Wire ISO 20022 (domestic and intl.) Domestic Wire / International Wire
icl Check (ICL) Check (ICL)
cash Cash orders/deposits (vault, moved by armored courier) Created by GIB from vault reports or by bank staff; not client-submittable. Carries the order or deposit details in cash_order / cash_deposit

Wires, both domestic and international, are submitted under ISO 20022 (wire20022).

Subtransactions

Many programs run nested flows: payments from many end users bundled into a single rail-level Transaction. The classic example is cross-border remittance: dozens or thousands of US-sender-to-foreign-beneficiary payments rolled into one outbound wire or ACH credit to a liquidity provider, who then pays out the underlying beneficiaries.

The bulk Transaction is what hits the rail. It tells GIB nothing about the true senders or the ultimate beneficiaries. Subtransactions are the per-end-user "true parties" record, linked to a parent Transaction. They are not themselves rail events; they are how GIB's monitoring, OFAC screening, and Travel Rule compliance reach the actual end-user level inside a bulk flow.

If your program bundles end-user payments (remittance, mass payouts, payroll, marketplace settlements), you almost certainly need Subtransactions. See the Subtransactions concept page for the data model, the link semantics, and the ultimate_beneficiary_subclient_id field on createTransaction that auto-creates a Subtransaction when you submit the parent.

Lifecycle

Transactions progress through these states. The platform enforces the allowed transitions between them and rejects moves it doesn't permit.

Two guarantees worth knowing: posted is only ever reached through processed (a direct update to posted from created, processing, or under_review is accepted but routed through processed first), so the processed webhook always fires before the posted webhook. And every move to failed or canceled carries a state_change_reason explaining why.

State Meaning
pending_settlement / created Initial state on successful submission
processing Actively being submitted to the network or applied to the ledger
under_review Manual review (compliance, risk, exception handling)
processed Submitted and acknowledged by the network; not yet final
posted Terminal, fully settled
failed Terminal, could not be completed
canceled Terminal, canceled before processing began

Clients can cancel a Transaction only while its Batch is still created. The platform allows cancellation from the other non-processing states (pending_settlement, under_review, processed) as well, but never once a Transaction is processing: reverse with a new Transaction or, for BOOK, submit an opposite-direction transfer.

For a hands-on walkthrough of checking a payment's status, finding it by trace identifier, and retrieving proof of payment, see the Tracking a Payment guide.

About under_review

A share of submitted transactions enter the under_review state for manual compliance or risk review by GIB's operations team. Typical triggers include OFAC near-matches, amounts unusually large relative to a program's profile, repeated authorization-related returns from a receiver, or pattern-based BSA flags. Reviews resolve to one of processing or processed (cleared), failed, or canceled.

While a Transaction is under_review:

  • The funds are not yet sent to the rail.
  • You receive a webhook on the under_review state transition and another webhook when GIB resolves the review.
  • If a user-facing situation requires escalation, contact operations@gibank.com with the Transaction ID.

For programs that need to communicate delays to end users, treat under_review as a soft-hold state in your UX and update the user once you receive the resolution webhook.

Fields

The Transaction object carries these fields beyond its id and state:

Field Purpose
type The rail (see types)
transfer_type Sub-type within the rail (e.g. batch, return, iat_batch, noc)
transfer_direction inbound (money entered your account) or outbound (money left your account)
data_direction incoming (file originated at another bank, arriving at GIB), outgoing (file originated from you, leaving GIB), or internal (BOOK transfer between GIB accounts)
transfer_flow push (origin → destination) or pull (destination → origin)
amount Amount in cents (no decimals)
origin_account_number / destination_account_number The primary account numbers involved
has_virtual_origin / origin_account_number_virtual Flag and original virtual account number, if origin was a virtual account
has_virtual_destination / destination_account_number_virtual Same for destination
trace_reference Unique identifier within the rail (IMAD for wire, Trace Number for ACH, etc.)
trace_reference_original For returns, points to the original Transaction's trace_reference
trace_reference_final Final reference, often updated after external system processing (e.g. confirmation IMAD for wire)
payment_info Additional payment-related text, varies by rail
return_code If a return, the specific reason code (e.g. R01 for ACH)
company_id The Company the Transaction is attributed to
user_id The User who submitted
batch_id The Batch this Transaction belongs to

The purpose field

Several Transaction-creation endpoints accept a purpose field on the request body, and Subtransactions carry their own purpose. The semantics differ by rail:

  • On the base API, BOOK, ACH, and Subtransactions, purpose is a free-text description of why the payment is being made (e.g. "Payroll for week ending 2026-05-20", "Marketplace settlement", "Remittance"). It travels with the record and is visible to GIB's monitoring and to operations during exception handling.
  • On international wires, purpose is encoded as a structured ISO 20022 purpose code rather than free text. It is either a standard ISO code (<Cd>) or a country-specific proprietary code (<Prtry>). Some destination countries (China, UAE, India, others) require a purpose code; the wire will be rejected or delayed without one. See the Purpose Code Reference for the standard code list, the Country-specific guides for per-country requirements, and International Wire → Transfer purposes and details for the rail-level walkthrough.

Set purpose accurately. It's especially important on bulk flows where the field describes what category of activity is in the bundle, and on cross-border wires where it's regulatorily required.

Two direction fields, two meanings

transfer_direction (inbound/outbound) reflects money flow relative to your account and drives webhook event naming. data_direction (incoming/outgoing/internal) reflects file origin (whether the entry came from another bank or was submitted by you) and is what automated-return rules evaluate. Don't conflate them.

Preconditions for creating a transaction

For user-initiated Transactions, the Subclient (or their associated Subclient Account if virtual) must reference at least one of the routing/account combinations involved (origin or destination). Every Transaction is submitted by a single User; see Companies & Users → The submission constraint. Virtual Accounts are internally linked to their parent core account, so funds directed to a Virtual Account route to the underlying core account; the API preserves both for tracking and reconciliation.

Submission options: test and simulate

Two boolean flags can be set on the request body when creating a Transaction (via createTransaction or the per-rail file-create endpoints):

  • test: marks the Transaction as a test. Useful for sandbox flows that should remain distinguishable from real submissions in search, reporting, and reconciliation. Per the OpenAPI: "Indicates if the transaction is a test transaction."
  • simulate: when true, runs creation as a simulation only. The request goes through validation, the response shape is returned as if successful, but no Transaction is stored. The returned IDs are set to -1. Per the OpenAPI: "Indicates if it's only a simulation or if the transaction must be stored permanently. If True, returned IDs are set to -1."

simulate is useful for client-side testing that exercises your handlers' parse-and-respond paths without committing data. test is useful for sandbox or production-test scenarios where you want a real record but want to keep it segregated from real activity.

Webhook events

State transitions emit events in the format {direction}_{type}_transaction_{state}:

  • outbound_ach_transaction_created, ..._processing, ..._processed, ..._posted, ..._failed, ..._canceled, ..._under_review, ..._updated, ..._pending_settlement
  • inbound_ach_transaction_* (same suffixes)
  • Same patterns for wire, wire20022, book, icl
  • Bulk creation failures emit {type}_transaction_create_failed (direction unknown)

Returns and NOCs ride the same webhook stream; identify them via the Transaction's transfer_type field (return, iat_return, noc).

See Webhooks for the full event-type catalog and delivery semantics.