OTP and Verify
OTP SMS for Malawi, with the checking done for you
The Verify API makes a one-time code, sends it to a +265 number and checks what the person typed. Your system never stores a code, and each code sent is one normal SMS.
Two calls: start and check
POST /v1/verify/start sends the code and returns an id. When the person types the code into your app, POST /v1/verify/check tells you whether it is right.
Starting again for the same number replaces the open code, so only the newest one works.
All the fields and responsesPOST /v1/verify/start
Authorization: Bearer yanu_live_YOUR_KEY
{ "to": "+265990000000", "app_name": "Shop" }
# 201 Created
{ "id": "vrf_8f2c...", "status": "pending" }
POST /v1/verify/check
{ "id": "vrf_8f2c...", "code": "482913" }
# 200 OK
{ "status": "approved", "valid": true }Why not just send the code yourself?
No codes in your database
Codes are stored only as a keyed hash and removed when the check finishes, so a leaked table gives nobody a working code.
Expiry and tries handled
Each code has a time limit and a number of wrong tries. When either runs out the verification closes by itself.
Limits against SMS abuse
Attackers sometimes trigger codes in bulk to run up your bill. Limits per key, per number and per account stop that from going far.
What people receive
Shop: your verification code is 482913. It expires in 5 minutes. Do not share it.
Keep your own wording short and plain. Say who it is from, how long the code lasts, and that it must not be shared. Fraud often starts with a caller asking for a code, so that last line matters. Use your own sender ID so the message is easy to recognise.
Default settings and limits
| Code length | 6 digits by default, 4 to 8 allowed |
|---|---|
| Time limit | 5 minutes by default, 1 to 30 allowed |
| Wrong tries per code | 5 by default, 1 to 10 allowed |
| Wait between resends | 30 seconds |
| Codes to one number | 5 in any 10 minutes |
SMS codes suit sign-ups, logins and payment confirmations, and they work on any phone. Delivery can never be promised, so give people a way to ask for a new code. Banks and SACCOs can read more on alerts and login codes.
Questions
What does an OTP SMS cost?
Each code sent is one normal SMS at K20 per part, and the default message fits in one part. Checking a code costs nothing. If the gateway refuses the message, it is not charged.
Do I need to generate and store the codes myself?
No. The Verify API makes the code, sends it and checks it. It keeps only a keyed hash, so nobody can read a code back, and your system stores just the verification id.
Can I test without sending real SMS?
Yes. With a yanu_test_ key, or test set to true, nothing is sent or charged and the code comes back in sandbox_code so your tests can use it.
Can I use my own wording?
Yes. Pass a template that contains {code}. You can also add {minutes} for the time limit, or pass app_name to use the default wording with your name.
Does the Verify API work for numbers outside Malawi?
No. Verify sends to Malawi numbers (+265) only.
Keep reading
Try Verify with a test key
Make a test verification and get the code back in the response, with no SMS and no charge.