Validate Mobile Money Account

Validate phone number

curl --request POST \
  --url https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountType": "mobile_money",
  "phoneNumber": "+254712345678",
  "shortCode": "247247",
  "accountReference": "0670179741746",
  "countryCode": "KE",
  "network": "MPESA",
  "accountName": "Jane Doe"
}
'

import requests

url = "https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money"

payload = {
    "accountType": "mobile_money",
    "phoneNumber": "+254712345678",
    "shortCode": "247247",
    "accountReference": "0670179741746",
    "countryCode": "KE",
    "network": "MPESA",
    "accountName": "Jane Doe"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountType: 'mobile_money',
    phoneNumber: '+254712345678',
    shortCode: '247247',
    accountReference: '0670179741746',
    countryCode: 'KE',
    network: 'MPESA',
    accountName: 'Jane Doe'
  })
};

fetch('https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountType' => 'mobile_money',
    'phoneNumber' => '+254712345678',
    'shortCode' => '247247',
    'accountReference' => '0670179741746',
    'countryCode' => 'KE',
    'network' => 'MPESA',
    'accountName' => 'Jane Doe'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money"

	payload := strings.NewReader("{\n  \"accountType\": \"mobile_money\",\n  \"phoneNumber\": \"+254712345678\",\n  \"shortCode\": \"247247\",\n  \"accountReference\": \"0670179741746\",\n  \"countryCode\": \"KE\",\n  \"network\": \"MPESA\",\n  \"accountName\": \"Jane Doe\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountType\": \"mobile_money\",\n  \"phoneNumber\": \"+254712345678\",\n  \"shortCode\": \"247247\",\n  \"accountReference\": \"0670179741746\",\n  \"countryCode\": \"KE\",\n  \"network\": \"MPESA\",\n  \"accountName\": \"Jane Doe\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountType\": \"mobile_money\",\n  \"phoneNumber\": \"+254712345678\",\n  \"shortCode\": \"247247\",\n  \"accountReference\": \"0670179741746\",\n  \"countryCode\": \"KE\",\n  \"network\": \"MPESA\",\n  \"accountName\": \"Jane Doe\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Phone number validated successfully.",
  "data": {
    "isValid": true,
    "isSupported": true,
    "requiresInternationalization": false,
    "countryCode": "KE",
    "countryName": "Kenya",
    "callingCode": "<string>",
    "internationalNumber": "+254712345678",
    "nationalNumber": "0712345678",
    "bankName": "<string>",
    "currency": "KES",
    "mno": "SAFARICOM KENYA",
    "message": "<string>",
    "accountName": "JANE MARY DOE",
    "nameLookupStatus": "MATCHED",
    "nameLookupReason": "Name lookup is not available for this payout corridor.",
    "matchScore": 95,
    "accountStatus": "ACTIVE",
    "nameMatch": {
      "provided": "Jane Doe",
      "score": 100,
      "matched": true,
      "threshold": 70,
      "masked": false
    }
  }
}

{
  "success": false,
  "message": "Invalid request",
  "data": {}
}

{
  "success": false,
  "message": "Unauthorized",
  "data": {}
}

POST

api

customer

validate

mobile-money

Validate phone number

curl --request POST \
  --url https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountType": "mobile_money",
  "phoneNumber": "+254712345678",
  "shortCode": "247247",
  "accountReference": "0670179741746",
  "countryCode": "KE",
  "network": "MPESA",
  "accountName": "Jane Doe"
}
'

import requests

url = "https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money"

payload = {
    "accountType": "mobile_money",
    "phoneNumber": "+254712345678",
    "shortCode": "247247",
    "accountReference": "0670179741746",
    "countryCode": "KE",
    "network": "MPESA",
    "accountName": "Jane Doe"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountType: 'mobile_money',
    phoneNumber: '+254712345678',
    shortCode: '247247',
    accountReference: '0670179741746',
    countryCode: 'KE',
    network: 'MPESA',
    accountName: 'Jane Doe'
  })
};

fetch('https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountType' => 'mobile_money',
    'phoneNumber' => '+254712345678',
    'shortCode' => '247247',
    'accountReference' => '0670179741746',
    'countryCode' => 'KE',
    'network' => 'MPESA',
    'accountName' => 'Jane Doe'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money"

	payload := strings.NewReader("{\n  \"accountType\": \"mobile_money\",\n  \"phoneNumber\": \"+254712345678\",\n  \"shortCode\": \"247247\",\n  \"accountReference\": \"0670179741746\",\n  \"countryCode\": \"KE\",\n  \"network\": \"MPESA\",\n  \"accountName\": \"Jane Doe\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountType\": \"mobile_money\",\n  \"phoneNumber\": \"+254712345678\",\n  \"shortCode\": \"247247\",\n  \"accountReference\": \"0670179741746\",\n  \"countryCode\": \"KE\",\n  \"network\": \"MPESA\",\n  \"accountName\": \"Jane Doe\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.kotanipay.com/api/v3/customer/validate/mobile-money")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountType\": \"mobile_money\",\n  \"phoneNumber\": \"+254712345678\",\n  \"shortCode\": \"247247\",\n  \"accountReference\": \"0670179741746\",\n  \"countryCode\": \"KE\",\n  \"network\": \"MPESA\",\n  \"accountName\": \"Jane Doe\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Phone number validated successfully.",
  "data": {
    "isValid": true,
    "isSupported": true,
    "requiresInternationalization": false,
    "countryCode": "KE",
    "countryName": "Kenya",
    "callingCode": "<string>",
    "internationalNumber": "+254712345678",
    "nationalNumber": "0712345678",
    "bankName": "<string>",
    "currency": "KES",
    "mno": "SAFARICOM KENYA",
    "message": "<string>",
    "accountName": "JANE MARY DOE",
    "nameLookupStatus": "MATCHED",
    "nameLookupReason": "Name lookup is not available for this payout corridor.",
    "matchScore": 95,
    "accountStatus": "ACTIVE",
    "nameMatch": {
      "provided": "Jane Doe",
      "score": 100,
      "matched": true,
      "threshold": 70,
      "masked": false
    }
  }
}

{
  "success": false,
  "message": "Invalid request",
  "data": {}
}

{
  "success": false,
  "message": "Unauthorized",
  "data": {}
}

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.

Use the account test values to reproduce unresolvable numbers, timeouts and mismatched names on demand.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

accountType

enum<string>

default:mobile_money

What to validate. Defaults to mobile_money; paybill and till take shortCode instead of phoneNumber.

Available options:

mobile_money,

paybill,

till

phoneNumber

string

Required unless accountType is paybill or till. Send it in international format, including the country code.

Example:

"+254712345678"

shortCode

string

Required when accountType is paybill or till. The M-PESA shortcode.

Example:

"247247"

accountReference

string

Account number on a paybill — what a payer would enter. Paybill only.

Example:

"0670179741746"

countryCode

string

Country code (ISO2). Only needed for paybill and till, where it defaults to KE.

Example:

"KE"

network

enum<string>

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.

Available options:

MTN,

AIRTEL,

VODAFONE,

TIGO,

YAS,

ORANGE,

NOT_SUPPORTED,

ZAMTEL,

MPESA,

CHECKOUT,

BKTRX,

CRDTRX,

MOOV,

TMONEY,

FREE,

EXPRESSO,

HALOPESA,

VODACOM,

WAVE

Example:

"MPESA"

accountName

string

Name you expect on this account. Returns a nameMatch score against the real one.

Example:

"Jane Doe"

Response

success

boolean

Example:

true

message

string

Example:

"Phone number validated successfully."

data

object

Show child attributes

Getting Started

Health & System

Authentication & Setup

Fiat Wallets

Crypto Wallets

Customer Management

Mobile Money Deposits

Mobile Money Withdrawals

Card Deposits

Bank Deposits

On-Chain Deposits

Bank Withdrawals

Kenya Withdrawals

Country & Service Support

Exchange Rates

Onramp (Buy Crypto)

Offramp (Sell Crypto)

Settlement Requests

Settlement Batches

Saved Beneficiaries

Cross-Border Payments

KYC & Compliance

Bulk Payments

Validate Mobile Money Account

Reading the result

Authorizations

Body

Response

​Reading the result

Authorizations

Body

Response

Reading the result