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. All balances and transaction amounts are 64-bit integers (long) in kobo — available_balance: 100000 means ₦1,000.

Incoming escrow (informational)

incoming_escrow is the sum of seller_amount across open escrows where this user is the seller — statuses active, awaiting_confirmation, and disputed. It answers the seller's question "how much money is on its way to me?"

It is informational, not spendable: while an escrow is open, the money itself sits locked in the buyer's escrow_balance. The two fields are different lenses on the same single ledger entry — nothing is double-counted, and incoming_escrow is never part of available_balanceor this user's own escrow_balance.
When the buyer confirms delivery, the amount leaves incoming_escrowand lands in this user's available_balance (marketplace sellers may then be paid out to their bank automatically).
A refund or a dispute resolved for the buyer removes it from incoming_escrow without ever crediting the seller — which is exactly why it is not a balance.
Like every amount: a 64-bit integer (long) in kobo.

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://vault-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,
    "incoming_escrow": 300000,
    "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://vault-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 }
}