Skip to content

Accounts

GIB's account model has two layers:

  1. Core Accounts: DDA or FBO accounts at GIB associated with your program (the Company record).
  2. Subclient Accounts: accounts assigned to a Subclient, the end user. A Subclient Account can be one of three types: virtual (the most common), core (a discrete bank account for the Subclient), or external (tracking an account at another bank).

For most fintechs, day-to-day work happens at the Subclient Account layer, almost always as Virtual Accounts: the per-Subclient sub-accounts you create, configure, and close as end users come and go. The Core Accounts that back them are typically configured once at onboarding and rarely change.

This page covers all of it.

At a glance

Layer What it is Lifecycle Operations
Core Accounts DDA or FBO accounts at GIB associated with your program. Where funds actually live. Bank-mediated; configured at onboarding Read-only via API (list, get, balance, statements)
Subclient Accounts Accounts assigned to a Subclient. Three types: core / virtual / external. Self-serve via API for virtual and external; bank-mediated for core Full CRUD for virtual and external; get/list/update/balance/close for core
Virtual Accounts (a deep-dive on the most common Subclient Account type) Sub-accounts that map to a parent Core Account. Each has a unique 12-digit account number routable through ACH and wire networks. Self-serve via API Full CRUD via the Subclient Account endpoints with type=virtual

Core Accounts

A Core Account is a DDA (Demand Deposit Account) or FBO (For-Benefit-Of) account at GIB, with a routing number, an account number, a balance, and a place on GIB's general ledger. These are the on-ledger anchors that every Transaction ultimately credits or debits.

Account purposes

Operationally most programs structure Core Accounts by purpose:

Purpose Description
Operational Day-to-day transactions, fee receipts, internal accounting
FBO (For-Benefit-Of) Holds customer funds on behalf of Subclients; typically the parent of many Virtual Accounts
Reserve Required reserves per the program agreement (NACHA-related, fraud reserves)
Settlement Holds funds in transit (e.g. between when a same-day ACH is initiated and when it settles)

Your account structure is configured during onboarding. To add Core Accounts after launch, contact your GIB account team.

DDA vs. FBO Distinction

The account object is fully agnostic of the legal account structure. Whether your end-user funds sit in a single FBO or in many discrete sub-DDAs is a legal/program choice you make with the bank during onboarding; the API surfaces both the same way.

That said, the operational implications differ. FBOs require Reconciliation (you maintain the per-customer ledger; GIB compares it daily). Discrete DDAs don't.

Core Account object

Field Purpose
id GIB identifier
user_id The User this account belongs to
account_number Account number
description Optional description
active True unless the bank has frozen the account
virtual_count Number of virtual accounts under this core account
company_name Name of the owning Company
create_date_time When the account was created
update_date_time When the account was last updated

Note: routing_number, purpose, balance_pending, and balance_available are not returned by the Core Account endpoints. Use getBalance for balance information.

Operations

Operation Description API reference
List accounts All Core Accounts associated with your program getUserAccounts
Get balance Retrieve pending and available balances getBalance

Core Accounts cannot be self-serve created, modified, or closed. These actions are bank-side operational changes; coordinate with your GIB account team.

Overdraft protection

For each Core Account, the bank can set a flag to automatically reject outbound Transactions that would cause an overdraft. See Returns → Core Account Overdraft Rejection. When enabled, all outbound Transactions for that account in the same Batch are rejected together.

Subclient Accounts

A Subclient Account is an account assigned to a Subclient. It's how money is tracked for a specific end user within your program. Subclient Accounts come in three types, each with different semantics.

The three types

Type What it is Backed by When to use
core A discrete, segregated bank account at GIB for the Subclient A discrete Core Account When the Subclient should have a fully-segregated bank account. Bank-mediated: core Subclient Accounts are not created via the API; GIB provisions them on your behalf.
virtual A sub-account that maps to a parent core or FBO account A parent Core Account, via a foreign-key link The most common type. Many Subclients share one underlying FBO and you maintain the customer-facing ledger. Self-serve: create programmatically via the API. See Virtual Accounts below for the deep dive.
external An account owned by the Subclient at another bank Not backed by GIB When tracking funding from / disbursement to a Subclient's account at another institution. Self-serve: create programmatically via the API.

Most fintechs use virtual Subclient Accounts as their primary type. Virtual accounts give every Subclient a unique routing/account-number pair while keeping the underlying funds in a single FBO at GIB, the one-FBO-many-virtual model that defines fintech-via-sponsor-bank.

Fields

Common across all types:

  • id: GIB's identifier
  • subclient_id: the parent Subclient
  • type: core / virtual / external
  • active: whether the account can transact
  • incoming_behavior: automated-return policy for incoming ACH debits (external "ACH pull" requests). Set to return_debits to block ACH pulls against the account (see Returns → Block ACH Debits)
  • outgoing_va_overdraft_behavior: overdraft policy on outbound (virtual only)
  • external_key: your platform's identifier for this account, for reconciliation hand-off

Virtual-account-specific:

  • virtual_account_number: the 12-digit account number assigned to this virtual account
  • parent_core_account_id: the Core Account it maps to

External-account-specific:

  • routing_number and account_number: the Subclient's account at the other bank

Operations

Operation Description API reference
Create Subclient Account (virtual or external) Provision a new Virtual or External account for a Subclient createSubclientAccount
List Subclient Accounts List for a given Subclient getSubclientAccounts
Update Subclient Account Update mutable fields including active, incoming_behavior, outgoing_va_overdraft_behavior updateSubclientAccount
Get virtual account balance Retrieve pending and available balance for a virtual account getBalanceVirtual

core Subclient Accounts are not creatable via the API. Contact your GIB account team to provision one; the operations above (get, list, update, balance, close) work on core Subclient Accounts the same as on virtual and external once they exist.

Inactive Subclient Accounts

Setting active = false on a Subclient Account stops it transacting. For virtual Subclient Accounts specifically, an inactive account triggers the Inactive Virtual Account automated return on any inbound ACH (returned with R02). Outbound transactions from an inactive account are rejected.

Configuring automated returns

Each Subclient Account can be configured for automated handling of inbound and outbound ACH:

See Returns → Automated Returns for the full configuration model and the return codes generated.

Virtual Accounts

Getting started: for a step-by-step walkthrough provisioning a Subclient and its first Virtual Account, see Create a Subclient with a Virtual Account.

Virtual Accounts (also known in some markets as Virtual IBANs or vIBANs) are GIB's primary mechanism for fintechs that ledger many end users on a single underlying bank account. They are one of the three Subclient Account types, and by far the most common: each Virtual Account has a unique 12-digit account number routable through the ACH and wire networks, but its funds sit in a parent FBO Core Account at GIB. From outside the bank, every Virtual Account looks like a standalone account; from inside, every Virtual Account's funds are pooled in one FBO that you reconcile against daily.

This is the layer most fintechs interact with most heavily, provisioning a Virtual Account per Subclient, configuring its policies, querying its balance, and closing it when the customer relationship ends. It's also the layer with the most operational nuance, because the one-FBO-many-virtual model carries reconciliation and configuration responsibilities that don't apply to discrete DDAs.

When to use Virtual Accounts

Virtual Accounts fit fintech models where you maintain the user-facing ledger and want each end user to have a unique routing/account number for inbound funding without operating a separate bank account per user:

  • E-wallet platforms (each customer has a Virtual Account)
  • Marketplace platforms (each merchant has a Virtual Account; one platform FBO)
  • Property management (each tenant has a Virtual Account for rent collection)
  • Group payment products (each member has a Virtual Account; group balance sheet)
  • Wage advance / payroll fintechs (each employee has a Virtual Account)

The key applications cluster around reconciliation enhancement (assigning unique account numbers to specific customers, departments, or invoices to simplify payment identification) and POBO/COBO (Payments and Collections On Behalf Of), where Virtual Accounts let you offer accounts in your customers' names with payments sent and received in their names. Crucial to any of these use cases is your responsibility for maintaining the ledger and the resulting reconciliation obligation.

When you create a Virtual Account programmatically, you reference an already-existing parent Core Account (the FBO that GIB provisioned for your program at onboarding); that's how GIB knows which Core Account to sub-ledger the Virtual Account under. You can't create the parent Core Account through the API.

Enabling Virtual Accounts for your program

Virtual Accounts are a program-level feature that must be enabled by the GIB bank team during onboarding (or in a follow-up engagement after launch). Once enabled, a 4-digit virtual_identifier is assigned to your program and you can create individual Virtual Accounts self-serve via the API. To enable Virtual Accounts on a program that doesn't already have them, contact your GIB account team.

How Virtual Accounts work

When you create a Virtual Account for a Subclient:

  1. GIB generates a unique 12-digit account number using your program's 4-digit virtual_identifier prefix plus an 8-digit unique sequence. The prefix, and therefore the generated numbers, may differ between Sandbox and Production; this is intentional, to avoid account numbers from one environment being unintentionally mixed up with the other. See Account number generation.
  2. The Virtual Account is associated with a parent Core Account, typically your FBO
  3. Inbound entries to the Virtual Account's number arrive at the parent Core Account; GIB internally maps them back to the Virtual Account for reporting
  4. Outbound entries originated from the Virtual Account debit the parent Core Account; the Virtual Account number appears in the trace for reconciliation

The parent / virtual mapping is bidirectional and stable. From your perspective, you transact against Virtual Accounts; GIB internally settles against the parent.

Account number generation

A 4-digit virtual_identifier is assigned to your program at onboarding. Virtual Account numbers are constructed as:

[virtual_identifier (4 digits)] + [unique sequence (8 digits)] = 12-digit virtual account number

For example, with virtual_identifier = 5000, GIB issues 500000000001, 500000000002, and so on. The unique sequence is GIB-assigned; you cannot pick specific numbers.

Per-Virtual-Account configuration

Per Virtual Account, you control:

  • active: true while the Virtual Account can transact. Setting to false triggers the Inactive Virtual Account automated return on any inbound ACH (returned with R02). Outbound transactions fail with 422.
  • incoming_behavior: controls the Block ACH Debits feature. return_debits auto-returns incoming external ACH debits ("ACH pulls") with R29, regardless of balance; the only exception is the micro-deposit carve-out (an account whose incoming debits in a single ACH file total under $1.00).
  • outgoing_va_overdraft_behavior: controls Virtual Account Overdraft Rejection (rejects outbound Transactions that would overdraft the Virtual Account, returned as HTTP 402 PaymentRequired).

See Returns → Automated Returns for the full configuration model and the return codes generated.

Reconciliation requirement

Programs using Virtual Accounts must perform daily reconciliation with GIB:

  1. Submit your expected balances for every Virtual Account
  2. Submit the Transactions you've processed in the period
  3. GIB compares against our records and reports any discrepancies

This requirement is foundational, not optional. It exists because the bank must be able to defend the parent FBO's aggregate balance against the per-Subclient ledger you maintain. See Reconciliation for the complete workflow, endpoints, and discrepancy handling.

Account state and Transactions

Several rails check the source or destination account's active flag at submission. If a Core Account is frozen:

  • Outbound: the Transaction fails with 403 ForbiddenError (see Errors)
  • Inbound: the entry is returned via the rail's normal return path

For Subclient Accounts (especially Virtual), an inactive flag triggers automatic returns under defined conditions. See Returns → Automated Returns and the per-account configuration section above.