Wallets

A wallet is a named balance container under your account. Every account can hold many wallets, each in a single currency, so you can separate funds by purpose — operations vs. payouts float, per-branch or per-product balances, per-currency balances, escrow, or sub-merchant ledgers — without opening separate accounts.

New. Wallets are an additive capability. If you never reference a wallet, everything behaves exactly as before: money lands in your default wallet and your existing integration keeps working unchanged.

The default wallet

Every account is created with one wallet flagged is_default: true, in the account's default_currency. It's the wallet used whenever a request omits wallet_id. You can't delete the default wallet, but you can rename it or designate a different wallet as the default.

What a wallet holds

Each wallet exposes two balances, both in the wallet's currency (decimal major units):

available — spendable now (e.g. payable out, or transferable).
pending — reserved for in-flight operations (e.g. a payout that hasn't finalized). Moves back to available if the operation fails.

Balances are per wallet. The account-wide Statement aggregates across all of an account's wallets.

How money moves

Direction	Endpoint	Wallet behavior
In	`POST /v1/payments`	Credits the wallet named by `wallet_id` on success (default wallet if omitted).
Out	`POST /v1/payouts`	Debits the wallet named by `wallet_id` (default wallet if omitted).
Between wallets	`POST /v1/transfers`	Moves funds between two wallets of the same account, instantly.

Inbound funds for a payment credit the chosen wallet only when the payment succeeds. Refunds debit the same wallet the payment credited.

Currency

A wallet is single-currency. There is no FX:

A payment or payout's currency must match the target wallet's currency.
A transfer's two wallets must share the same currency.

To hold multiple currencies, create one wallet per currency.

Transfers

Transfers are ledger-only and synchronous — they never touch external rails, so they settle immediately (no callback, no fee). A transfer either succeeds atomically or fails with 422 (e.g. insufficient available balance); there is no pending transfer state. See the Transfers API.

Ledger mapping

Each wallet is backed by its own ledger accounts, mirroring the single-balance layout but namespaced by wallet id:

merchant:<id>:wallet:<wallet_id>:payable:<CUR>
merchant:<id>:wallet:<wallet_id>:payable_pending:<CUR>

Every wallet operation is a double-entry posting that sums to zero, so the sum of all wallet balances always equals the account's total payable.

Limits

A wallet can't be deleted while it holds a non-zero balance, or while it's the default wallet — move funds out (transfer or payout) first.
A wallet has two interchangeable identifiers: its id (a stable wlt_… value) and its number (an 8-digit account number, e.g. 47514771). Pass either as wallet_id (or from_wallet_id / to_wallet_id) — the two formats never collide, so resolution is unambiguous. Omitting wallet_id always selects the default wallet.
Per-account wallet count is capped (default 50); contact us to raise it.

Wallets & Transfers API — create, list, balance, transfer.
Payments API — wallet_id on inbound payments.
Payouts API — wallet_id on outbound payouts.