Core Concepts¶
This section describes the data model and the platform behaviors that apply across every service GIB exposes. Read it once when you start; refer back to it from any service page.
The data model is small. There are roughly a dozen first-class objects, with predictable relationships between them. Get this right and the rest of the API surface, the rails, the operations, the workflow tooling, falls into place.
Data model¶
| Concept | What it represents |
|---|---|
| Companies & Users | Your fintech and the human / programmatic actors who operate it |
| Subclients | The end users of your program (businesses or natural persons) |
| Subclient Accounts | The abstraction layer that ties accounts (core, virtual, or external) to a Subclient |
| Balances | Pending vs. available, memo-posted vs. hard-posted |
| Transactions | The fundamental record of money movement, with a defined lifecycle |
| Subtransactions | The per-end-user "true parties" record linked to a Transaction. Used to de-nest bulk transactions where one rail event represents many end-user payments (cross-border remittance, mass payouts, etc.). Essential for BSA / OFAC / Travel Rule defensibility. |
| Batches & Files | Groupings of transactions and the four submission workflows (direct, delayed, bulk, bulk-delayed), plus accepted file formats per rail |
| Returns | Reversing or rejecting an earlier Transaction across any rail. Includes Automated Returns for configuring GIB to return inbound entries on your behalf. |
Platform behavior¶
| Concept | Why it matters |
|---|---|
| Webhooks | Real-time signed HTTP events delivered to your server on every state change |
| Notifications | Email and dashboard inbox alerts; mandatory for returns, NOCs, and discrepancies |
| Reconciliation | Daily reconciliation when using virtual accounts |
| Security | Authentication, transport, masking, duplicate detection |
| Idempotency | Safely retrying POST requests via the external_key body field |
| Errors | Error response shape and full code catalog |
| Pagination | How list endpoints page results: limit/offset, the shared envelope, walking a full list |
Suggested reading order¶
The Getting Started guide is the hands-on companion to this section; read it in parallel to get sandbox credentials and make your first API call.
If you're integrating from scratch:
- Companies & Users, who's who in the platform
- Subclients and Subclient Accounts, how end users are represented
- Balances, where money lives. Then visit the Accounts service for the operational details on both Core and Virtual Accounts.
- Transactions, how money moves
- Subtransactions, if your program bundles end-user payments into bulk transactions (cross-border remittance, mass payouts, etc.)
- Batches & Files, how transactions are grouped and submitted
- Webhooks and Notifications, staying informed via programmatic events, email, and dashboard
- Returns, including Automated Returns for inbound rejection logic
- Idempotency, Errors, Security, production-grade integration
- Reconciliation, if your program uses virtual accounts
Then move to the Services section for the rail-by-rail operations and lifecycles.