Skip to main content
Use these endpoints to retrieve your Kulmi Pay wallets and create new working wallets. Settlement wallets are provisioned automatically when you activate a currency — you only need the POST endpoint to create additional working wallets for fund separation or specific disbursement flows. Base URL: https://app.kulmipay.com

​
List wallets

GET /api/v1/wallets/ Returns all wallets associated with your business, including both settlement and working wallets. To retrieve a single wallet, use GET /api/v1/wallets/{wallet_id}/. 
curl --request GET \
  --url https://app.kulmipay.com/api/v1/wallets/ \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

​
Create a wallet

POST /api/v1/wallets/ Creates a new working wallet on your account. You cannot create SETTLEMENT wallets — those are managed by Kulmi Pay automatically.

​
Request parameters

​
currency
string
required
Currency for this wallet. One of: KES, USD, EUR, GBP.
​
wallet_type
string
required
Must be WORKING. Settlement wallets are created automatically and cannot be created through this endpoint.
​
label
string
required
A friendly name for this wallet. Must be unique within the same currency on your account. Alphanumeric characters only.
​
can_disburse
boolean
default:"false"
Set to true to allow this wallet to be used as the source for disbursements. Defaults to false.
curl --request POST \
  --url https://app.kulmipay.com/api/v1/wallets/ \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "KES",
    "wallet_type": "WORKING",
    "label": "Payroll Wallet",
    "can_disburse": true
  }'

​
Wallet object

Both the list and create endpoints return wallet objects in the following shape.
​
wallet_id
string
The wallet alias ID. Use this value to identify the wallet in all other endpoints, for example when initiating a transfer or retrieving transactions.
​
currency
string
The currency this wallet holds. One of KES, USD, EUR, or GBP.
​
wallet_type
string
Either SETTLEMENT (auto-created) or WORKING (created by you).
​
label
string
The friendly name you assigned to this wallet.
​
available_balance
string
Funds immediately available to spend. This excludes amounts that are still clearing or on hold.
​
current_balance
string
Total balance on the wallet, including funds that have not yet cleared.
​
can_disburse
boolean
Whether this wallet can be used as the source for disbursements.
​
updated_at
string
ISO 8601 timestamp of the last time the wallet balance was updated.

​
Example response

{
  "wallet_id": "wlt_abc123",
  "label": "Payroll Wallet",
  "can_disburse": true,
  "currency": "KES",
  "wallet_type": "WORKING",
  "current_balance": "50000.00",
  "available_balance": "50000.00",
  "updated_at": "2024-04-16T09:30:00Z"
}
The wallet_id returned in this response is the alias ID. Always use this value — not the internal database ID — when referencing a wallet in other API calls.