Wallet Products
Define product templates that control wallet behavior: tiers, currency, and account code patterns.
A wallet product is a template that defines how wallets of that type behave. Think of it as a blueprint: when you create a wallet, you specify which product it belongs to, and the product determines the default tier, currency, and underlying ledger account code.
The WalletProduct object
{
"id": "wp_01HZ...",
"name": "Savings Account",
"code": "SAVINGS",
"ownerType": "Individual",
"defaultTier": "Unverified",
"defaultCurrency": "GHS",
"accountCodeTemplate": "CLIENT-{ownerId}",
"isActive": true,
"metadata": null,
"createdAt": "2026-04-01T10:00:00Z",
"updatedAt": null
}Prop
Type
The accountCodeTemplate controls how ledger accounts are named. For
example, CLIENT-{ownerId} creates accounts like CLIENT-user_42. A
merchant product might use MERCHANT-{ownerId} to separate account
namespaces.
ownerType: who is allowed to open this product
ownerType is an access restriction. Every wallet owner is either an
Individual (a person) or a Business (an organization). Setting this
field pins the product to one kind of owner:
Individual: only individuals can open a wallet on this product. A request withownerType: "Business"is rejected with422.Business: only organizations.null(omit it): any owner type is accepted.
The check happens at wallet creation: if the product declares an
ownerType and the request's ownerType doesn't match, the wallet is
refused. This is how you stop, say, a personal wallet from being opened
against a merchant product by mistake.
Example. A school-fees platform might define a WARD product with
ownerType: "Individual" (each student is a person) and a SCHOOL
product with ownerType: "Business" (each school is an org). The engine
then guarantees student wallets and school wallets can never be opened
against the wrong product.
defaultTier: the starting limits level for new wallets
A tier is a trust/verification level that governs how much money a
wallet is allowed to move. defaultTier is simply the tier every new
wallet inherits at creation; individual wallets can later be moved up or
down with upgrade-tier.
There are exactly three tiers, in increasing order of trust:
| Tier | Typical meaning |
|---|---|
Unverified | Brand-new wallet, no KYC done yet. Tightest limits. |
Basic | Some identity verification completed. Moderate limits. |
Full | Fully verified (full KYC). Highest or no limits. |
The tier by itself does nothing. It's just a label until you attach
transaction limits to it. Limits are resolved by
(product, tier, transaction type, currency), so a limit you create for
the Unverified tier only applies to wallets currently at that tier.
Raising a wallet's tier is what unlocks the higher limits you configured
for that tier. If you define no limits for a tier, wallets at that
tier are effectively unlimited.
Create a product
/api/v1/banking/wallet-productsRequest body
Prop
Type
curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallet-products" \
-H "X-Api-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Savings Account",
"code": "SAVINGS",
"ownerType": "Individual",
"defaultTier": "Unverified",
"defaultCurrency": "GHS",
"accountCodeTemplate": "CLIENT-{ownerId}"
}'Status codes
| Code | When |
|---|---|
201 | Product created |
409 | A product with this code already exists |
422 | Validation error (missing fields, invalid currency, template missing {ownerId}) |
List products
/api/v1/banking/wallet-productsQuery parameters
Prop
Type
curl "https://api.shiwake.example.com/api/v1/banking/wallet-products?isActive=true" \
-H "X-Api-Key: sk_live_..."Get a product
/api/v1/banking/wallet-products/{id}curl "https://api.shiwake.example.com/api/v1/banking/wallet-products/wp_01HZ..." \
-H "X-Api-Key: sk_live_..."Get by code
/api/v1/banking/wallet-products/by-code/{code}curl "https://api.shiwake.example.com/api/v1/banking/wallet-products/by-code/SAVINGS" \
-H "X-Api-Key: sk_live_..."Update a product
/api/v1/banking/wallet-products/{id}Only include the fields you want to change.
Request body
Prop
Type
Deactivating a product does not close existing wallets. It only prevents new wallets from being created with this product.
curl -X PATCH "https://api.shiwake.example.com/api/v1/banking/wallet-products/wp_01HZ..." \
-H "X-Api-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "isActive": false }'Last updated on