Skip to main content
Kulmi Pay gives your business a set of wallets to hold funds in multiple currencies. Every payment you collect lands in a wallet, and every disbursement you send draws from one. You can keep balances in Kenyan shillings, US dollars, euros, and British pounds — all within the same account.

​
Wallet types

There are two kinds of wallets in Kulmi Pay: Settlement wallets are created automatically when you activate a currency on your account. Collected payments are deposited here. You cannot create or delete settlement wallets — Kulmi Pay manages them for you. Working wallets are wallets you create for a specific purpose — for example, a payroll wallet or an operations fund. You control when to create them, what to label them, and whether they can be used to disburse funds.
Settlement wallets are provisioned automatically. You only need to create working wallets when you want to separate funds for a specific use case.

​
Supported currencies

CurrencyCode
Kenyan ShillingKES
US DollarUSD
EuroEUR
British PoundGBP

​
View your wallet balances

Send a GET request to /api/v1/wallets/ to retrieve all wallets on your account. 
curl --request GET \
  --url https://app.kulmipay.com/api/v1/wallets/ \
  --header "Authorization: Bearer <your-token>"
The response returns a list of wallet objects: 
{
  "results": [
    {
      "wallet_id": "wlt_abc123",
      "label": "default",
      "can_disburse": true,
      "currency": "KES",
      "wallet_type": "SETTLEMENT",
      "current_balance": "125000.00",
      "available_balance": "120000.00",
      "updated_at": "2024-11-01T09:30:00Z"
    },
    {
      "wallet_id": "wlt_def456",
      "label": "Payroll Wallet",
      "can_disburse": true,
      "currency": "KES",
      "wallet_type": "WORKING",
      "current_balance": "50000.00",
      "available_balance": "50000.00",
      "updated_at": "2024-11-01T08:00:00Z"
    }
  ]
}
The two balance fields mean different things:
  • available_balance — the amount you can spend right now. Funds that are still clearing or on hold are excluded.
  • current_balance — the total balance on the wallet, including funds that haven’t cleared yet.
To retrieve a single wallet, use GET /api/v1/wallets/{wallet_id}/.

​
Create a working wallet

Send a POST request to /api/v1/wallets/ with the following body: 
{
  "currency": "KES",
  "wallet_type": "WORKING",
  "label": "Payroll Wallet",
  "can_disburse": true
}
FieldTypeRequiredDescription
currencystringYesOne of KES, USD, EUR, GBP.
wallet_typestringYesMust be WORKING.
labelstringYesA name for this wallet. Must be unique within the same currency on your account.
can_disbursebooleanNoSet to true to allow disbursements from this wallet. Defaults to false.
The response returns the created wallet object with its assigned wallet_id.