Ledgers & Accounts
The core of SwitchLock is a double-entry bookkeeping system. Every entity on the platform owns a Ledger, which acts as a container for multiple Accounts representing different currencies or purposes.
Ledgers vs Accounts
A Ledger belongs to an entity (a User, the Company, or the System). It groups accounts together and holds default bank payout details. An Account is the actual leaf node holding a numeric balance in a specific currency (USD or ZIG) for a specific purpose.
- CLEARINGUSD/ZIG
- BANK_COLLECTIONUSD/ZIG
- UNALLOCATEDUSD/ZIG
- REVENUEUSD/ZIG
- PAYOUT_GLUSD/ZIG
- USERUSD
- USERZIG
Account Types
| Type | Ledger Owner | Purpose |
|---|---|---|
| USER | User | Available balance owned by the user. Funds here can be paid out. |
| REVENUE | Company | Your accumulated platform fees and margins. |
| ESCROW | Company | Funds locked in active escrow transactions waiting for release. |
| PAYOUT_GL | Company | Liability account representing funds requested for payout but not yet settled. |
| CLEARING | System | Temporary holding for incoming deposits before reconciliation (T+1 physical bank settlement). |
| BANK_COLLECTION | System | Reflects physical cash held in the platform's actual banking partners. |
User initialization
When you register a new user on your tenant via the Users API, the system immediately provisions their financial environment. A USER Ledger is created, containing two default accounts ready to receive funds:
Because these accounts are created automatically during signup, you rarely need to create accounts manually. You can immediately accept deposits into these automatically provisioned accounts.
Integer balances
All financial amounts in the API are represented as integers (BigInts) in the smallest currency unit. For USD, 100 means $1.00. Do not use floats or decimals in API requests.
You'll see stringified numbers in JSON responses (e.g. "balance": "100") because JavaScript Number loses precision for very large 64-bit integers. Always parse these to your language's BigInt or Decimal equivalents.
List user accounts
Retrieves all accounts (USD, ZIG) associated with a user's ledger.
curl "https://api.switchlock.co.zw/v1/ledger/user/usr_01HXYZ.../accounts" \
-H "x-api-key: zl_sk_your_key_here" \
-H "x-company-id: cmp_01HXYZ..."[
{
"id": "acc_01HABC...",
"ledgerId": "ldg_01HABC...",
"type": "USER",
"currency": "USD",
"balance": "15000",
"is_frozen": false,
"created_at": "2026-06-20T10:00:00.000Z",
"updated_at": "2026-06-23T14:00:00.000Z"
},
{
"id": "acc_01HDEF...",
"ledgerId": "ldg_01HABC...",
"type": "USER",
"currency": "ZIG",
"balance": "0",
"is_frozen": false,
"created_at": "2026-06-20T10:00:00.000Z",
"updated_at": "2026-06-20T10:00:00.000Z"
}
]Get account details
Retrieves current balance and info for a specific account. This endpoint includes the parent ledger details and user info.
curl "https://api.switchlock.co.zw/v1/ledger/accounts/acc_01HABC..." \
-H "x-api-key: zl_sk_your_key_here" \
-H "x-company-id: cmp_01HXYZ..."{
"id": "acc_01HABC...",
"type": "USER",
"currency": "USD",
"balance": "15000",
"is_frozen": false,
"ledger": {
"id": "ldg_01HABC...",
"name": "User Ledger - Jackson Doe",
"type": "USER",
"user": {
"id": "usr_01HXYZ...",
"first_name": "Jackson",
"last_name": "Doe"
}
}
}Get ledger overview
Retrieves a consolidated view of accounts for a specific ledger, summarizing balances across currencies.
curl "https://api.switchlock.co.zw/v1/ledger/overview/ldg_01HABC..." \
-H "x-api-key: zl_sk_your_key_here" \
-H "x-company-id: cmp_01HXYZ..."{
"ledgerId": "ldg_01HABC...",
"accounts": [
{
"id": "acc_01HABC...",
"currency": "USD",
"balance": "15000",
"type": "USER"
},
{
"id": "acc_01HDEF...",
"currency": "ZIG",
"balance": "0",
"type": "USER"
}
],
"totalBalance": "15000"
}Update default bank details
Ledgers hold default payout instructions. When a payout is triggered without specifying bank details, the system falls back to the ledger's defaults.
curl -X PATCH "https://api.switchlock.co.zw/v1/ledger/ldg_01HABC.../bank-details" \
-H "x-api-key: zl_sk_your_key_here" \
-H "x-company-id: cmp_01HXYZ..." \
-H "Content-Type: application/json" \
-d '{
"bank_name": "First Capital Bank",
"branch_code": "0000",
"account_number": "123456789",
"account_name": "Jackson Doe"
}'