> ## 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 Mobile Money Account
> Validates a phone number in any format (with or without country code). Returns validation status, country information, formatted number, and whether the country is supported for mobile money.
Checks a recipient before you pay them: the number format, the country it belongs
to, and whether that corridor is supported.
**Send phone numbers in international format**, with the country code. If we can't
determine the country from the number, the response tells you so rather than guessing
a corridor and validating the wrong one.
For **paybill and till**, there is no useful format check: a shortcode is just
digits, and whether it exists is exactly what the lookup answers. Those two types
therefore require name lookup to be enabled on your account.
## Reading the result
`nameLookupStatus` tells you whether the name resolved, and `nameLookupReason`
says why when it didn't — so you can tell a number that doesn't exist from a
corridor that can't resolve names from something worth retrying.
`isValid` reports the number format, and flips to `false` once a lookup proves the
destination unusable. A name **mismatch** is different: the number 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
unresolvable numbers, timeouts and mismatched names on demand.
## OpenAPI
````yaml POST /api/v3/customer/validate/mobile-money
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/mobile-money:
post:
tags:
- CUSTOMER - VALIDATION
summary: Validate phone number
description: >-
Validates a phone number in any format (with or without country code).
Returns validation status, country information, formatted number, and
whether the country is supported for mobile money.
operationId: AccountValidationController_validateMobileMoneyAccount_api/v3
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateMobileMoneyAccountDto'
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
success:
type: boolean
example: true
message:
type: string
example: Phone number 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:
ValidateMobileMoneyAccountDto:
type: object
properties:
accountType:
type: string
description: >-
What to validate. Defaults to mobile_money; paybill and till take
shortCode instead of phoneNumber.
enum:
- mobile_money
- paybill
- till
default: mobile_money
phoneNumber:
type: string
description: >-
Required unless accountType is paybill or till. Send it in
international format, including the country code.
example: '+254712345678'
shortCode:
type: string
description: Required when accountType is paybill or till. The M-PESA shortcode.
example: '247247'
accountReference:
type: string
description: >-
Account number on a paybill — what a payer would enter. Paybill
only.
example: '0670179741746'
countryCode:
type: string
description: >-
Country code (ISO2). Only needed for paybill and till, where it
defaults to KE.
example: KE
network:
type: string
description: >-
Mobile network, used to route the name lookup. Optional — it is
resolved from the phone number prefix when omitted. Supply it only
if the number has been ported, or if the response tells you the
network could not be determined.
enum:
- MTN
- AIRTEL
- VODAFONE
- TIGO
- YAS
- ORANGE
- NOT_SUPPORTED
- ZAMTEL
- MPESA
- CHECKOUT
- BKTRX
- CRDTRX
- MOOV
- TMONEY
- FREE
- EXPRESSO
- HALOPESA
- VODACOM
- WAVE
example: MPESA
accountName:
type: string
description: >-
Name you expect on this account. Returns a nameMatch score against
the real one.
example: Jane Doe
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
````