How the objects fit together

Customers and accounts

A customer is a person or a business. An account is opened for one or more customers on one version of a product. Its owners array holds their ids. The first is the primary owner and is repeated as customer_id.

Every account has exactly one ledger account, named in ledger_account_id, and that is where its balance lives. It also has one or more account numbers. Each number routes payments to the account, and all of them land on the same balance.

Transfers

A transfer moves money between an account and a counterparty over a rail, or between two accounts at the bank. Each rail has its own object and id prefix. GET /transfers lists ACH, wire, realtime and book transfers in one shape.

Two ids tie a transfer to the ledger. hold_id names the hold that reserves the funds while a payment is in flight. journal_id names the journal that moved the money once it posted.

The ledger and events

Every change to a balance is a journal: debit and credit entries that balance. A hold reserves part of a balance without moving it. Journals are never edited. A correction is a new journal.

A state change also produces an event. Events are listed at /events and delivered to webhook endpoints.

Ids

An id is a type prefix, an underscore and 27 characters drawn from 0-9, A-Z and a-z. The leading characters encode the creation time, so ids of one type sort in creation order. That order is what cursor pagination pages by.