Withdrawals

Withdrawals move funds from a user's available_balance to their verified bank account via Monnify disbursement. Your app should check the wallet balance, ensure a bank account exists, then request a withdrawal on behalf of the user.

Withdrawal statuses

pending → processing → successful
        ↘ failed (funds returned to available balance)
        ↘ cancelled

Limits & fees

• Minimum withdrawal: ₦1,000 (100,000 kobo)
• Maximum withdrawal: ₦5,000,000 (configurable per environment)
• A small flat or percentage fee may apply (see your Kashia agreement)

Complete flow

1. GET /external/users/:userId/wallet — confirm available balance
2. GET /external/users/:userId/bank-accounts — pick a verified account (or add one first)
3. POST /external/users/:userId/withdrawals — initiate payout
4. Listen for withdrawal.initiated, withdrawal.successful, or withdrawal.failed webhooks

Endpoints

curl -X POST https://api.kashiahq.com/api/v1/external/users/USER_UUID/withdrawals \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9500000,
    "bank_account_id": "BANK_ACCOUNT_UUID",
    "currency": "NGN"
  }'

{
  "success": true,
  "data": {
    "id": "uuid",
    "reference": "WTH-a1b2c3d4",
    "amount": 9500000,
    "fee": 5000,
    "net_amount": 9495000,
    "currency": "NGN",
    "status": "processing",
    "bank_account": {
      "bank_name": "Guaranty Trust Bank",
      "account_number": "0123456789",
      "account_name": "JOHN DOE"
    },
    "created_at": "2025-01-15T10:30:00Z"
  }
}