Wallets Docs — Mozaca Labs

SandboxUpdated May 28, 2026

Wallet model

In Fedha, wallets represent customer-facing balance and movement state inside a client deployment. A wallet can have primary, secondary, held, pending, and available states depending on customer profile, KYC tier, and route configuration.

A wallet is not useful without identity, ledger, funding route, client context, transaction evidence, and operator visibility. Mozaca keeps those dependencies visible in the API and customer, merchant, agent, admin, and BI surfaces.

Create a wallet

Create wallets from your backend after the client and customer identity path are known. For regulated flows, the identity state, tier limits, and operator policies must be accepted before funding or transfer operations are enabled.

POST /walletsbash

curl https://api.mozacalabs.com/v1/wallets \
  -X POST \
  -H "Authorization: Bearer MOZACA_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wallet-demo-001" \
  -d '{
    "customerId": "cus_184250",
    "label": "Primary wallet",
    "currency": "KES",
    "metadata": {
      "channel": "mobile"
    }
  }'

Wallet responsejson

{
  "id": "wallet_kes_184250",
  "status": "pending_review",
  "currency": "KES",
  "availableBalance": "0.00",
  "identityState": "review_required",
  "createdAt": "2026-05-28T10:24:00Z"
}

Read balances

Balance reads return available, pending, and reserved amounts so product teams can explain what a customer can use and what is still settling.

GET /wallets/{id}/balancesjson

{
  "walletId": "wallet_kes_184250",
  "balances": [
    {
      "asset": "KES",
      "available": "184250.00",
      "pending": "3200.00",
      "reserved": "0.00"
    }
  ],
  "ledgerState": "matched"
}

Receipts

Every wallet movement should close with a customer receipt and an operator event. Receipts are designed to support customer support, reconciliation, and audit review.