> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kotanipay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Validate Bank Account
> Validates a bank account number format for a given country and bank code, and whether the country is supported.
Checks a bank account before you pay it: the account number format, the bank code,
and whether the country is supported.
With name lookup enabled, the response also carries the name registered on the
account and its status — a frozen or restricted account will usually reject an
incoming payment, so it's worth checking before you send.
## Reading the result
`nameLookupStatus` tells you whether the name resolved, and `nameLookupReason` says
why when it didn't — so you can tell an account that doesn't exist from a corridor
that can't resolve names from something worth retrying.
`isValid` reports the account number format, and flips to `false` once a lookup
proves the destination unusable. A name **mismatch** is different: the account is
real, so `isValid` stays `true` and `nameMatch.matched` is what tells you the
holder isn't who you expected.
Full status meanings, retry guidance, and how these fields relate are on
[Account Validation](/v3/essentials/account-validation).
Use the [account test values](/v3/testing/sandbox-scenarios) to reproduce
frozen, unresolvable and mismatched-name accounts on demand.
## OpenAPI
````yaml POST /api/v3/customer/validate/bank
openapi: 3.0.0
info:
title: KOTANI PAY API PLATFORM
description: ''
version: '3.0'
contact: {}
servers:
- url: https://sandbox-api.kotanipay.com
security: []
tags: []
paths:
/api/v3/customer/validate/bank:
post:
tags:
- CUSTOMER - VALIDATION
summary: Validate bank account
description: >-
Validates a bank account number format for a given country and bank
code, and whether the country is supported.
operationId: AccountValidationController_validateBankAccount_api/v3
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateBankAccountDto'
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
success:
type: boolean
example: true
message:
type: string
example: Bank account validated successfully.
data:
$ref: '#/components/schemas/ValidateAccountResponseDto'
type: object
'400':
description: ''
content:
application/json:
schema:
properties:
success:
type: boolean
example: false
message:
type: string
example: Invalid request
data:
type: object
example: {}
'401':
description: ''
content:
application/json:
schema:
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
data:
type: object
example: {}
security:
- JWT: []
components:
schemas:
ValidateBankAccountDto:
type: object
properties:
accountNumber:
type: string
description: Bank account number
example: '1234567890'
bankCode:
type: string
description: Bank code or name
example: KCB
countryCode:
type: string
description: Country code
example: KE
accountName:
type: string
description: >-
Name you expect on this account. Returns a nameMatch score against
the real one.
example: Jane Doe
required:
- accountNumber
- bankCode
- countryCode
ValidateAccountResponseDto:
type: object
properties:
isValid:
type: boolean
description: Whether the phone number or account is valid
example: true
isSupported:
type: boolean
description: Whether the country/service is supported
example: true
requiresInternationalization:
type: boolean
description: >-
Whether the phone number needs internationalization (missing country
code)
example: false
countryCode:
type: string
description: Country code (ISO2)
example: KE
countryName:
type: string
description: Country name
example: Kenya
callingCode:
type: string
description: Phone number calling code (e.g., +254)
internationalNumber:
type: string
description: >-
Phone number in international format without spaces (e.g.,
+254712345678)
example: '+254712345678'
nationalNumber:
type: string
description: Phone number in national format without spaces (e.g., 0712345678)
example: '0712345678'
accountType:
type: string
description: Account type
enum:
- mobile_money
- bank
- paybill
- till
bankName:
type: string
description: Bank name (for bank accounts)
currency:
type: string
description: Currency for the country
example: KES
network:
type: string
description: >-
The mobile network the lookup was routed on — either the one you
sent, or the one resolved from the number's prefix. Mobile money
only.
enum:
- MTN
- AIRTEL
- VODAFONE
- TIGO
- YAS
- ORANGE
- NOT_SUPPORTED
- ZAMTEL
- MPESA
- CHECKOUT
- BKTRX
- CRDTRX
- MOOV
- TMONEY
- FREE
- EXPRESSO
- HALOPESA
- VODACOM
- WAVE
mno:
type: string
description: >-
The mobile network operator the number belongs to, resolved from its
prefix. Mobile money only.
example: SAFARICOM KENYA
message:
type: string
description: Validation error message (if invalid)
accountName:
type: string
description: Name registered on the account. Requires name lookup to be enabled.
example: JANE MARY DOE
nameLookupStatus:
type: string
description: >-
MATCHED, NOT_FOUND, ACCOUNT_UNAVAILABLE, UNSUPPORTED, TIMEOUT, ERROR
or NOT_ENABLED. NOT_FOUND means nothing is there;
ACCOUNT_UNAVAILABLE means the account exists but cannot receive
money.
enum:
- MATCHED
- NOT_FOUND
- ACCOUNT_UNAVAILABLE
- UNSUPPORTED
- TIMEOUT
- ERROR
- NOT_ENABLED
example: MATCHED
nameLookupReason:
type: string
description: >-
Why the name lookup ended in that status. Populated for every
outcome other than MATCHED and NOT_ENABLED, so a failed lookup is
always actionable rather than a bare status code.
example: Name lookup is not available for this payout corridor.
matchScore:
type: number
description: >-
Confidence the resolved name is the right one, 0-100. Only returned
where the corridor scores its own match.
example: 95
accountStatus:
type: string
description: 'Account status: ACTIVE, FROZEN or RESTRICTED.'
example: ACTIVE
nameMatch:
description: >-
Comparison of the accountName you sent against the name on the
account.
allOf:
- $ref: '#/components/schemas/NameMatchDto'
required:
- isValid
- isSupported
- accountType
NameMatchDto:
type: object
properties:
provided:
type: string
description: The name you supplied on the request.
example: Jane Doe
score:
type: number
description: How closely the names match, 0-100.
example: 100
matched:
type: boolean
description: Whether the score met your account threshold.
example: true
threshold:
type: number
description: The threshold the score was compared against.
example: 70
masked:
type: boolean
description: True when the provider masked part of the name — weaker evidence.
example: false
required:
- provided
- score
- matched
- threshold
- masked
securitySchemes:
JWT:
scheme: bearer
bearerFormat: JWT
type: http
````