ShiwakeDocs

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 with ownerType: "Business" is rejected with 422.
  • 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:

TierTypical meaning
UnverifiedBrand-new wallet, no KYC done yet. Tightest limits.
BasicSome identity verification completed. Moderate limits.
FullFully 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

POST/api/v1/banking/wallet-products

Request 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

CodeWhen
201Product created
409A product with this code already exists
422Validation error (missing fields, invalid currency, template missing {ownerId})

List products

GET/api/v1/banking/wallet-products

Query 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

GET/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

GET/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

PATCH/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 }'
Edit on GitHub

Last updated on

On this page