Wallet & Ledger
Interact with the double-entry ledger to manage pockets, holds, and transfers.
Wallet & Ledger
daayOS includes a built-in double-entry ledger for managing funds. At signup, a primary wallet is created for every user with an initial balance of 0 in an available pocket.
Core Concepts
- Wallets: The top-level container for a user or organization’s funds.
- Pockets: Sub-balances within a wallet (e.g.,
available,reserved). - Holds: Temporary reservations of funds that can be captured or voided later.
- Transfers: Moving funds between wallets or between pockets within a wallet.
API Endpoints
All wallet operations sit under /v1/api/wallet. (Note: The legacy /v1/api/user/wallets endpoints delegate to these newer paths).
| Method | Path | Description |
|---|---|---|
| GET | /v1/api/wallet |
List wallets for the authenticated user |
| GET | /v1/api/wallet/:id |
Get details for a specific wallet and its pockets |
| POST | /v1/api/wallet/transfer |
Transfer funds between wallets or pockets |
| POST | /v1/api/wallet/holds |
Place a hold on funds (reserve them) |
| POST | /v1/api/wallet/holds/:id/capture |
Capture a previously placed hold |
| POST | /v1/api/wallet/holds/:id/void |
Void a hold and return funds to the available pocket |
Using the Ledger
Viewing Balances
To see a user’s current balances, fetch their wallets:
GET /v1/api/wallet
Authorization: Bearer <token>Holds and Escrow
When a transaction needs to be authorized before it is finalized, you can place a hold. This moves funds from the available pocket to a reserved state. Once the condition is met, you capture the hold to finalize the transfer, or void it to return the funds.
Note: Live money-rail wiring (e.g., payouts to external bank accounts) is currently deferred until a payout provider is finalized. The system currently tracks internal ledger movements only.