Skip to content

Reconciliation

Reconciliation is the daily process of comparing your records of virtual account balances and transactions against GIB's. It exists because, for programs that use virtual accounts and operate the end-user-facing ledger, the bank's records and the client's records must match every day to remain regulator-defensible.

If your program uses virtual accounts and you maintain the end-user-facing ledger, daily reconciliation is mandatory.

Reconciliation submission

GIB exposes a single reconciliation endpoint, clientReconciliationData, that accepts both the per-account balance snapshot and the per-period transaction list in a single request. The body has two top-level shapes:

  • Inline payload — for small submissions, use the data field with an array of ClientReconciliationData objects.
  • URL reference — for larger submissions (>10 MB) or when re-using a generated file, use the url field pointing to an S3 URL or pre-signed URL. Get an upload URL with getFileUploadUrl.
POST /reconciliation/data
{
  "data": [
    {
      "accounts": [
        {
          "account_number": "500000000001",
          "account_type": "virtual",
          "balance": 12500,
          "withheld_balance": 0
        }
      ],
      "transactions": [
        {
          "transaction_id": 1234,
          "origin_routing_number": "091001322",
          "origin_account_number": "12345",
          "origin_account_type": "core",
          "destination_routing_number": "091208154",
          "destination_account_number": "500000000001",
          "destination_account_type": "virtual",
          "amount": 1000
        }
      ]
    }
  ]
}

For very large submissions:

POST /reconciliation/data
{
  "url": "https://s3.amazonaws.com/.../reconciliation-2026-05-04.json"
}

What gets submitted

Field Required Notes
accounts[] Yes Submit your expected balances for all virtual accounts you control
accounts.account_number Yes The virtual account number
accounts.account_type Yes Must be virtual
accounts.balance Yes Your record of the account's USD balance, in cents
accounts.withheld_balance Optional Funds withheld at your platform, in cents
transactions[] Yes All Transactions you processed in the period
transactions.transaction_id Optional The GIB Transaction ID (number), if known
transactions.amount Yes Amount in cents
transactions.origin_* / destination_* Yes Routing number, account number, and account type (core or virtual) for each side

Include accounts even if there were no balance changes during the period — they confirm to GIB that your record agrees with the bank's record of "no change."

What counts as a relevant transaction

GIB does not compare your submission against every row in its transaction table. It compares against a defined "relevant" set, and your transactions[] list should match the same set so you don't see spurious discrepancies.

A transaction is relevant when it is:

  • Real, not a test: test transactions are excluded.
  • Not deleted: soft-deleted records are excluded.
  • Attributed to a Company and has a positive amount.
  • Not failed or canceled, with one exception below.

On top of that, GIB resolves return chains so a single underlying movement is counted once:

  • A failed transaction is counted if it has at least one genuine (non-failed, non-canceled) return against it.
  • A return that has itself been dishonored by a later return-of-return is excluded, and the return-of-return itself is excluded.

Balance reconciliation includes return fees; the stricter posting-reconciliation set additionally drops "auto-rejected" returns whose original failed and that therefore never posted to the bank's core ledger. When in doubt about whether a specific edge-case transaction should appear in your submission, ask your GIB onboarding contact rather than guessing. Including a transaction GIB treats as irrelevant will surface as a discrepancy.

Timing

  • Submit your data after GIB's daily balance recalculation (the bank's nightly settlement cutoff).
  • Coordinate the exact submission window with your GIB onboarding contact; the cutoff varies by program configuration.

Response and discrepancy handling

The endpoint accepts the submission and queues it for comparison. Discrepancies between your data and GIB's records are surfaced through your operations channels (email and the dashboard inbox). For unresolved discrepancies, GIB operations contacts your program's primary contact via your established channel.

Reconciliation discrepancy notifications surface via email and the dashboard inbox; treat those as authoritative.