ShiwakeDocs

Wallets

Create and manage wallets: the user-facing containers for money, backed by liability accounts.

A wallet is a user-facing money container. Under the hood, each wallet maps 1:1 to a liability account in the core ledger. The wallet adds higher-level concepts: an owner, a product, a tier, a status, and human-readable metadata.

The Wallet object

{
  "id": "wal_01HZ...",
  "productId": "wp_01HZ...",
  "productCode": "SAVINGS",
  "accountId": "acc_01HZ...",
  "accountCode": "CLIENT-user_42",
  "ownerId": "user_42",
  "ownerType": "Individual",
  "displayName": "Kwame's Savings",
  "tier": "Unverified",
  "status": "Active",
  "currency": "GHS",
  "ledgerBalance": 150000,
  "availableBalance": 125000,
  "metadata": null,
  "createdAt": "2026-04-01T10:00:00Z",
  "updatedAt": null
}

Prop

Type

ledgerBalance is the true accounting balance. availableBalance is what the user can actually spend. It excludes any amounts reserved by pending withdrawals.

One wallet per owner per product

Each owner can have at most one wallet per product. If you need a user to have multiple wallets, create multiple products (e.g. SAVINGS, SPENDING, BUSINESS).


Create a wallet

POST/api/v1/banking/wallets

Opens a new wallet for the given owner on the specified product. This atomically creates the underlying ledger account and the wallet record.

Request body

Prop

Type

curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "SAVINGS",
    "ownerId": "user_42",
    "ownerType": "Individual",
    "displayName": "Kwame'\''s Savings"
  }'

Status codes

CodeWhen
201Wallet created
404Product not found
409Owner already has a wallet on this product
422Product inactive, owner type mismatch, invalid currency

List wallets

GET/api/v1/banking/wallets

Prop

Type


Get a wallet

GET/api/v1/banking/wallets/{id}

List by owner

GET/api/v1/banking/wallets/by-owner/{ownerId}

Returns all wallets for a specific owner across all products.


Freeze a wallet

POST/api/v1/banking/wallets/{id}/freeze

Prevents all money movement. The wallet cannot receive deposits, process withdrawals, or participate in transfers while frozen.

curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../freeze" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Suspicious activity flagged by compliance" }'

Unfreeze a wallet

POST/api/v1/banking/wallets/{id}/unfreeze

Restores a frozen wallet to Active status.

curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../unfreeze" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Investigation cleared" }'

Close a wallet

POST/api/v1/banking/wallets/{id}/close

Permanently closes a wallet. The wallet must have zero balance (both ledger and available). Closed wallets cannot be reopened.

Closing is irreversible. Ensure the wallet has been fully settled before closing.

Status codes

CodeWhen
200Status changed
404Wallet not found
409Wallet is already closed
422Cannot close: outstanding balance

Upgrade tier

POST/api/v1/banking/wallets/{id}/upgrade-tier

Changes the wallet's KYC tier. Tiers affect which transaction limits apply. Moving a wallet to a higher tier is what unlocks the limits you configured for that tier. The three tiers, lowest to highest trust, are Unverified, Basic, and Full.

Request body

Prop

Type

curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../upgrade-tier" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "tier": "Full" }'

Get limit usage

GET/api/v1/banking/wallets/{id}/limits/usage

Returns the wallet's current usage against all applicable transaction limits. How much has been used in each period and how much remains.

{
  "code": 200,
  "data": {
    "walletId": "wal_01HZ...",
    "tier": "Basic",
    "productName": "Savings Account",
    "limits": [
      {
        "transactionType": "Deposit",
        "period": "Daily",
        "maxAmount": 500000,
        "usedAmount": 150000,
        "remainingAmount": 350000,
        "currency": "GHS"
      },
      {
        "transactionType": "Withdrawal",
        "period": "Monthly",
        "maxAmount": 5000000,
        "usedAmount": 0,
        "remainingAmount": 5000000,
        "currency": "GHS"
      }
    ]
  }
}
Edit on GitHub

Last updated on

On this page