Bank Accounts

Users must add and verify a Nigerian bank account before withdrawing. Verification uses Monnify's real-time name lookup. Each user can save multiple accounts; one is marked as the default for withdrawals.

Recommended flow

GET /external/banks — populate a bank selector in your app
POST /external/bank-accounts/verify — confirm account number and display the resolved name
POST /external/users/:userId/bank-accounts — save the verified account for the user

Endpoints

GET/api/v1/external/banks

List supported Nigerian banks (cached from Monnify). Requires X-API-Key.

Request example

bash

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

Response

json

{
  "success": true,
  "data": [
    { "bank_code": "058", "bank_name": "Guaranty Trust Bank" },
    { "bank_code": "033", "bank_name": "United Bank for Africa" }
  ]
}

POST/api/v1/external/bank-accounts/verify

Verify an account number before saving. Does not create a bank account record.

Request example

bash

curl -X POST https://api.kashiahq.com/api/v1/external/bank-accounts/verify \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"bank_code":"058","account_number":"0123456789"}'

Response

json

{
  "success": true,
  "data": {
    "account_number": "0123456789",
    "account_name": "JOHN DOE",
    "bank_code": "058",
    "bank_name": "Guaranty Trust Bank"
  }
}

POST/api/v1/external/users/:userId/bank-accounts

Add a verified bank account for a user. Re-verifies via Monnify before saving.

Request example

bash

curl -X POST https://api.kashiahq.com/api/v1/external/users/USER_UUID/bank-accounts \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"bank_code":"058","account_number":"0123456789"}'

Response

json

{
  "success": true,
  "data": {
    "id": "uuid",
    "bank_code": "058",
    "bank_name": "Guaranty Trust Bank",
    "account_number": "0123456789",
    "account_name": "JOHN DOE",
    "is_default": true,
    "is_verified": true,
    "currency": "NGN"
  }
}

GET/api/v1/external/users/:userId/bank-accounts

List saved bank accounts for a user.

POST/api/v1/external/users/:userId/bank-accounts/:bankAccountId/set-default

Set the default withdrawal account.

DELETE/api/v1/external/users/:userId/bank-accounts/:bankAccountId

Delete a bank account. Fails if a pending withdrawal uses this account.