Wallet lifecycle

Creation and ownership

A wallet has an owner type, owner identifier, currency, and wallet type. Owner types include customer, business, branch, employee, and system contexts. Account number and owner are immutable after creation. Create a new wallet rather than attempting to transfer ownership of an existing wallet.

States

Wallet states are pending_activation, active, frozen, suspended, and closed. Full operation requires the active state. Some restricted states can allow reads while blocking writes. A client must not assume that the existence of a wallet means it can make a payment.

Understanding balance

cached_balance is the recorded snapshot, held_balance represents reserved funds, pending_balance represents pending value, and available_balance is currently usable. Call the balance endpoint instead of reproducing the subtraction in client code, because the contract can evolve.

Holds and releases

A hold is appropriate when a workflow must reserve value before capture or final decision. Persist the hold_uuid, and do not create another hold only because a release response was delayed. Set an expiry when the workflow requires one and handle expired states explicitly.

Freeze and ledger integrity

Freeze, unfreeze, and verify-integrity are restricted operations, not routine customer features. Integrity verification may be expensive and is intended for audit workflows. Financial corrections are represented by reversal entries, never by editing an original ledger entry.