Wallets

Every Kashia user has a wallet with three balance buckets: available, escrow, and pending. Balances are computed from the ledger — they are not stored as a single number. Available balance can be withdrawn; escrow balance is locked in active transactions; pending balance reflects in-transit withdrawals.

Balance buckets

available_balance — funds the user can withdraw after completed escrow releases
escrow_balance — funds locked while escrows are active or disputed
pending_balance — funds debited for withdrawals still processing with the payment provider

Endpoints

GET/api/v1/external/users/:userId/wallet

Get wallet balances for a user your merchant has transacted with. Requires X-API-Key.

Parameters
Parameter	Type	Required	Description
`userId`	uuid	No	Kashia user ID (path)
`currency`	string	No (default: NGN)	Currency code

Request example

bash

curl https://api.kashiahq.com/api/v1/external/users/USER_UUID/wallet \
  -H "X-API-Key: your_api_key"

Response

json

{
  "success": true,
  "data": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "available_balance": 9500000,
    "escrow_balance": 15000000,
    "pending_balance": 0,
    "currency": "NGN"
  }
}

GET/api/v1/external/users/:userId/wallet/transactions

List ledger entries for a user, filtered to escrows and withdrawals involving your merchant.

Parameters
Parameter	Type	Required	Description
`transaction_type`	string	No	Filter by ledger type
`direction`	string	No	credit or debit
`page`	integer	No (default: 1)	Page number
`per_page`	integer	No (default: 20)	Items per page

Request example

bash

curl "https://api.kashiahq.com/api/v1/external/users/USER_UUID/wallet/transactions?page=1" \
  -H "X-API-Key: your_api_key"

Response

json

{
  "success": true,
  "data": [
    {
      "id": "...",
      "reference": "WLT-abc123",
      "transaction_type": "escrow_release",
      "amount": 9700000,
      "currency": "NGN",
      "direction": "credit",
      "balance_type": "available",
      "escrow_id": "...",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 12, "total_pages": 1 }
}