Bank Accounts

Users must add and verify a Nigerian bank account before withdrawing. Verification uses the payment provider's real-time name lookup. Each user can save multiple accounts; one is marked as the default — automatic settlement payouts go to the default verified account (falling back to the newest verified account if none is marked default). Manual withdrawals name their destination explicitly: you pass a bank_account_id on each withdrawal request. For marketplace sellers you can also pass seller_bank_account directly when creating a payment link; it is verified and becomes the seller's default in one call.

Precondition: the /external/users/:userId/… routes work only for users who already have an escrow with your merchant — a freshly created customer with no paid transaction yet returns 404. To capture a seller's account before their first escrow exists, use seller_bank_account on payment-link creation.

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 the active payment provider). Requires X-API-Key.

Request example

bash

curl https://vault-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://vault-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 (returns 201). The account name is confirmed with the provider before saving; if the same account already exists for the user, the existing record is returned without a new lookup. A failed name enquiry returns 400 with the provider's reason.

Request example

bash

curl -X POST https://vault-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,
    "name_source": "bank_confirmed",
    "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 account — the destination for automatic settlement payouts. (Manual withdrawals pass their own bank_account_id.)

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

Delete a bank account. Returns 400 if a pending withdrawal still uses this account.