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
/api/v1/banking/walletsOpens 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
| Code | When |
|---|---|
201 | Wallet created |
404 | Product not found |
409 | Owner already has a wallet on this product |
422 | Product inactive, owner type mismatch, invalid currency |
List wallets
/api/v1/banking/walletsProp
Type
Get a wallet
/api/v1/banking/wallets/{id}List by owner
/api/v1/banking/wallets/by-owner/{ownerId}Returns all wallets for a specific owner across all products.
Freeze a wallet
/api/v1/banking/wallets/{id}/freezePrevents 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
/api/v1/banking/wallets/{id}/unfreezeRestores 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
/api/v1/banking/wallets/{id}/closePermanently 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
| Code | When |
|---|---|
200 | Status changed |
404 | Wallet not found |
409 | Wallet is already closed |
422 | Cannot close: outstanding balance |
Upgrade tier
/api/v1/banking/wallets/{id}/upgrade-tierChanges 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
/api/v1/banking/wallets/{id}/limits/usageReturns 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"
}
]
}
}Last updated on