Recipients

Check who owns a phone number or bank account before you pay it.

POSTVerify a recipient/api/v1/recipients/verify

Send your API key as Authorization: Bearer apk_test_… (sandbox) or apk_live_… (live). Each endpoint lists the scope the key needs. See API keys.

Verify a recipient

POST/api/v1/recipients/verify

API keyrecipients:read 30 a minute per key

Looks up the name on an M-Pesa, Airtel Money or bank account. Send the name you expect and we tell you whether it matches. Use it when someone gives you their number for the first time.

Body (JSON)

typestringrequired
What to check.
mobile_moneybank
phonestringoptional
mobile_money only: the Kenyan mobile number.
networkstringoptional
mobile_money only. Default "safaricom".
safaricomairtel
bank_codestringoptional
bank only: from GET /api/v1/banks.
account_numberstringoptional
bank only: 6 to 34 characters.
namestringoptional
The name you expect. When sent, name_match tells you how close it is.

Request

curl -X POST "https://api.autopayke.com/api/v1/recipients/verify" \
  -H "Authorization: Bearer $AUTOPAYKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mobile_money",
    "phone": "+254712345678",
    "name": "Jane Doe"
  }'

Response200 application/json

{
  "ok": true,
  "data": {
    "object": "recipient_check",
    "livemode": false,
    "resolved": true,
    "account_name": "JANE WANJIKU DOE",
    "name_match": "matched"
  }
}

Response fields

resolvedboolean
Whether the network returned a name. false can mean the account doesn't exist or the network doesn't share names for it.
account_namestring | null
The registered name, as the network returns it (often upper case).
name_matchstring | null
Only when you sent name. matched: every word of the shorter name appears in the other (Jane Doe matches JANE WANJIKU DOE). mismatch: they don't agree; confirm with the person before paying. unverified: nothing resolved to compare against. null when you didn't send a name.
matchedmismatchunverified

Errors

VALIDATION_ERRORRECIPIENT_INVALIDRATE_LIMITED

Plus the key and rate errors any keyed call can return.

Sandbox: every number resolves to JANE WANJIKU DOE except +254700000002, and every account except 0000000000.
Checking many numbers that don't resolve looks like sweeping for valid accounts and alerts our team. Only check numbers people gave you.