Core concepts
Updated 1 September 20263 min read
On this page
Ledgerline has two halves that work together. The ledger records who owns what, using double-entry bookkeeping. The payment rails move that money in and out of real bank accounts. This page names the objects you will meet in the API and shows how they relate.
The object map
| Object | ID prefix | What it is |
|---|---|---|
| Organization | n/a | Your company. Owns keys, plans, team members and a data region. |
| Ledger | led_ |
A container for related accounts, for example one per product line. |
| Account | acc_ |
A balance in a single currency, with a normal balance of debit or credit. |
| Transaction | txn_ |
A balanced group of entries that changes account balances. |
| Entry | ent_ |
One debit or credit against one account. Immutable once posted. |
| Transfer | trf_ |
An instant move between two accounts in the same organization. |
| Counterparty | cpt_ |
An external person or business you pay, with one or more bank accounts. |
| Payout | pay_ |
A payment from one of your accounts to a counterparty's bank account. |
| Event | evt_ |
A record of something that happened, delivered to your webhook endpoints. |
Ledgers and accounts
An account never holds a free-floating number. Its balance is always the sum of the entries posted to it, which makes every balance explainable and every change auditable. Read Ledgers and accounts for the model and Transactions and entries for the rules on balancing.
Two properties matter most in practice:
- Single currency per account. A ledger can hold accounts in several currencies, but each account has exactly one. See Multi-currency ledgers.
- Posted entries are immutable. You never edit or delete history. To correct a mistake you reverse the transaction, which writes new entries that cancel the old ones.
Moving money
Money moves in two ways, and the API keeps them separate on purpose.
- Transfers stay inside Ledgerline. A transfer between two of your accounts is instant, free and recorded as a balanced transaction.
- Payouts leave Ledgerline. A payout sends funds from an account to a counterparty over a payment rail such as ACH, wire, SEPA or an instant network. Rails have cut-offs, limits and settlement times, covered in Payment rails and Payouts.
Money arrives through virtual accounts. Each virtual account has its own routing and account number, and credits sent to it are posted to the ledger account it is attached to.
Events
Almost everything that changes state emits an event. Events are the supported way to learn that a payout was paid, a statement is ready or a verification finished. Subscribe with webhook endpoints and verify every delivery with the signature header.
Safety rails built into every request
- Authenticate with a bearer token. Keys are either full secret keys or restricted keys with scopes.
- Send an
Idempotency-Keyon everyPOSTso a retry can never create a second payout. See Idempotency. - Expect a rate limit of 600 requests per minute per API key. See Rate limits.
- Every response carries a
Ledgerline-Request-Idheader. Quote it when you investigate a problem.
Sandbox and live
Each organization has a sandbox and a live environment with separate keys, separate data and separate base URLs. The sandbox simulates banks so you can test happy paths and failures quickly. Live access is unlocked after business verification. See Sandbox and Going live.
Versions
The API is versioned by date through the Ledgerline-Version header. Your organization is pinned to the version that was current when you signed up, and nothing changes for you until you opt in. Read API versioning before you upgrade.