Bank Account

Verify a Kenyan bank account and resolve the account holder name via POST /api/v1/bank-account/ke. Call GET /api/v1/banks/ke first to obtain a valid bank_id. Other country codes are not supported yet. Verification HTTP 200 is billable; listing banks and validation/provider errors are not.

List supported banks

Returns every bank supported for Kenyan verification, each with an id and display name. Use id as bank_id on the verify request below. Auth required; this call is not billed.

GET/api/v1/banks/ke

{{baseUrl}}/api/v1/banks/ke

200 OKSample dataExample response

{
  "success": true,
  "response_code": 200,
  "message": "Banks fetched successfully",
  "country": "ke",
  "data": {
    "banks": [
      { "id": 1, "name": "KCB" },
      { "id": 8, "name": "Co-operative Bank" },
      { "id": 34, "name": "Equity Bank" },
      { "id": 42, "name": "Post Bank" }
    ],
    "count": 42
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
country	string	Country code from the path (ke)
data.banks	array	Supported banks, sorted by id ascending
data.banks[].id	integer	Value to send as bank_id when verifying
data.banks[].name	string	Bank display name for UI selection
data.count	integer	Number of banks in the list

Verify bank account

POST/api/v1/bank-account/ke

{{baseUrl}}/api/v1/bank-account/ke

Header

Header	Type	Description
Authorization	string	`Bearer YOUR_ACCESS_TOKEN` from the OAuth client-credentials flow
Content-Type	string	application/json

Body Parameters

Parameter	Type	Description	Required
account_number	string	Bank account number (max 50 characters)	required
bank_id	integer	Bank identifier from GET /api/v1/banks/ke (e.g. 34 = Equity Bank)	required
consent	boolean	Must be true — confirms data-subject consent to perform this verification	required
customer_number	string	Optional reference for your own tracking (max 255 characters)	optional

Sample request body

All verification APIs require consent: true in the JSON body.

Sample dataSample request body

{
  "account_number": "0123456789",
  "bank_id": 34,
  "consent": true
}

Response

200 OKSample dataExample response

{
  "success": true,
  "response_code": 200,
  "message": "Bank Account Details Fetched Successfully",
  "country": "ke",
  "data": {
    "account_number": "0123456789",
    "bank": { "id": 34, "name": "Equity Bank" },
    "account_holder": { "name": "JAMES KAMAU" },
    "status": "valid"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
response_code	number	Application response code (typically mirrors HTTP)
message	string	Human-readable status message
country	string	Country code from the path (ke)
data.account_number	string	Account number that was verified
data.bank.id	integer	Bank identifier used for the lookup
data.bank.name	string	Bank display name
data.account_holder.name	string	Resolved account holder name
data.status	string	"valid" when the account is confirmed; "invalid" otherwise
request_id	string	UUID for support and audit trails

Error codes

Standard Peleza HTTP / response_code values (same across all API calls). Validation message text is endpoint-specific. Full reference: Error Codes.

Code	When	Billed?
200	Account holder details returned	Yes
400	Validation — account_number / bank_id (unknown bank ID)	No
401	Missing or invalid Bearer token	No
402	Insufficient wallet balance or credit limit	No
403	No active wallet or billing profile (or service not enabled)	No
404	Resource not found after verification completed — or unsupported country	Yes (found path completed) / No (unsupported country)
408	Upstream timeout / service error	No
429	Rate limited	No
502	Upstream bad or unreadable response	No
503	Verification failed or service unavailable	No

Invalid bank ID

400Sample dataInvalid bank ID

{
  "success": false,
  "response_code": 400,
  "message": "Invalid bank ID provided. Please provide a valid bank ID.",
  "country": "ke",
  "errors": { "bank_id": ["Invalid bank ID"] },
  "request_id": "550e8400-e29b-41d4-a716-446655440030"
}

Verification failed

503Sample dataVerification failed

{
  "success": false,
  "response_code": 503,
  "message": "Bank account verification failed. Please check the account number and try again.",
  "country": "ke",
  "errors": {
    "account_number": ["Bank account verification failed. Please check the account number and try again."]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440031"
}

Set {{baseUrl}} to https://api.peleza.com (production) or https://sandbox.peleza.com (sandbox). Authenticated calls need a Bearer token from POST /api/v1/oauth/token.