To implement phone number verification in Kenya, collect the number, normalise it to +254 format, send a one-time code, verify the code the user types on your server, and protect the flow with expiry and limits. You can then add M-PESA verification and channel fallback for users and moments where SMS alone is not enough. This guide walks through the full flow, the security details that matter, and the Kenya-specific points to plan for.
Phone verification proves that someone controls a phone number right now. It is not identity verification. If your product is licensed and needs KYC or age checks, those are separate steps with their own rules.
What phone verification is for
- Confirming a real number at sign-up before a bonus or first transaction
- Protecting login from a new device or after a password reset
- Confirming a change of payout or contact number
- Reducing fake accounts and repeated sign-ups from the same person
- Account recovery without a support call
Step 1: collect the number well
Use a phone input that shows the +254 country code and accepts the formats people actually type. Tell the user why you need the number and what you will send.
- Accept 07xx, 01xx, 254 and +254 formats
- Strip spaces, dashes and brackets
- Convert to one canonical format such as E.164 before you send or store
- Validate length: nine digits after +254
- Reject obviously invalid numbers with a clear message
Step 2: send the code
Make the send request from your server. Include the number and, if your provider supports it, the channel or a delivery journey. Keep the reference the provider returns, because you need it to check the code later. Respond to the browser with a neutral message such as "we sent a code", so you do not reveal whether a number is already registered.
Step 3: show a clear input
- Show where the code was sent, with the last digits of the number
- Show a countdown that matches the code's expiry
- Add a resend button that waits a short cooldown
- Offer "send by WhatsApp" or "call me" after a delay
- Allow paste and autofill for one-time codes
Step 4: verify on the server
Check the code on your server, never in the browser. Compare it against the stored hash or call your provider's verify endpoint, and check the expiry and attempt count. Return the same message for wrong, expired and used codes. On success, mark the number as verified, store the time, and discard the code.
Step 5: protect the flow
- Use codes of at least six digits, single use, expiring within a few minutes
- Cap wrong attempts and lock the number for a time
- Rate limit sends per number, per account and per IP
- Do not let a resend reset the attempt count
- Add a country allowlist and a daily spend cap to limit SMS pumping
- Add a challenge before the first send if you see bots
- Re-verify when a number changes or when you see risky activity
NIST guidance sets at least six digits, single use and a maximum of 10 minutes for out-of-band codes, and calls for rate limiting of failed attempts. OWASP guidance adds that SMS codes are exposed to SIM swap and interception, so use a stronger method for high-value actions.
Kenya-specific points
- Number formats: accept and normalise all common formats
- M-PESA: widely used, so a PIN prompt can confirm a number without a typed code, which suits payout number changes
- Reverse OTP: the user sends a message instead of typing a code, which avoids waiting for an incoming SMS
- Sender ID: secondary sources describe registration of sender names for Kenyan traffic. Confirm current rules with your provider and the regulator
- Dual-SIM phones: the number the user gives may not be the SIM that receives messages well
- Connectivity: users move between data and weak signal, so offer more than one channel
Step 6: add fallback and M-PESA
Start with SMS. Add WhatsApp and a voice call as fallbacks, sending the same code on each so the user only enters one. For payouts and other high-risk steps in Kenya, offer an M-PESA verification, which confirms the number with a PIN prompt. Keep a fallback in case the prompt times out or the user is out of reach.
Using the Tambua API
Call POST /v1/otp/send with the phone number. Keep the otp_token from the response. When the user submits the code, call POST /v1/otp/verify with the token and the code. Leave out the channel to run your delivery journey, for example SMS then WhatsApp then voice, or pass channel=mpesa for an M-PESA prompt to a +254 number. Free test keys return the code in the API response, so you can test the whole flow without a phone. Signed webhooks tell you when a code is sent, delivered or verified. SMS OTP in Kenya is KES 0.50, and failed attempts are not billed. See the Tambua docs for details.
Step 7: test before you launch
- Try real Kenyan numbers on the networks your users have
- Test late delivery, resend, expiry, wrong code and lockout
- Test a number with no coverage and confirm fallback works
- Test the M-PESA path with a number that does not respond
- Confirm that logs and analytics never contain the code
- Run an automated test with a test key before every release
Common mistakes
- Verifying in the browser instead of on the server
- Letting a resend reset the attempt counter
- Revealing whether a number is already registered
- Using four-digit codes with no lockout
- Skipping the country allowlist and spend cap
- Treating a verified number as a verified identity
Frequently asked questions
How long should the code be valid? A few minutes is common. NIST allows up to 10 minutes. Shorter is safer but must allow for slow delivery.
Do I need to verify every login? Not usually. Verify at sign-up, on new devices, on risky actions and when a number changes.
Can I use email instead of a phone number? Yes for some products, but phone verification gives a stronger link to a real person and is common in mobile-first markets.
Is phone verification enough for KYC? No. It proves control of a number, not who the person is. Licensed products need their own identity checks.