Products
One-time passwords
Codes for logins, transfers and password resets, delivered on WhatsApp from your bank's own number, with a Copy code button. Your server sends a code, your customer types it into your app, and your server checks it.
How it works
- Your server calls
POST /otp/sendwith the customer's phone number and gets back anid. - The customer gets a WhatsApp message from your bank: "482913 is your verification code. For your security, do not share this code." with a Copy code button and the line "This code expires in 10 minutes."
- Your app asks for the code, and your server calls
POST /otp/verifywith theidand what the customer typed.
Motion 5 never stores the code itself, only a keyed hash of it, so nobody (including us) can read codes back.
/v1/otp/sendBody
phone08031234567, +2348031234567 or another country's number in international form.purposelogin or transfer. Shown in Developers and in events.ttl_secondslengthcurl https://motion5.dev/v1/otp/send \
-H "Authorization: Bearer $MOTION5_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "phone": "08031234567", "purpose": "login" }'Returns 201 with the OTP object. Errors: 422 invalid_phone, invalid_ttl or invalid_length; 429 too_soon or rate_limited (see limits); 409 no_number if your bank has no WhatsApp number connected yet; 502 send_failed if WhatsApp refused the message.
About the expiry line
/v1/otp/verifyBody
idid from /otp/send.code{ "valid": true }
{ "valid": false, "reason": "wrong_code", "attempts_left": 3 }
{ "valid": false, "reason": "expired" }Reasons
wrong_codeattempts_left says how many tries remain.expiredtoo_many_attemptsalready_usedcancelledfailedAn unknown id, or one from the other mode, gets 404 not_found.
/v1/otp/{id}curl https://motion5.dev/v1/otp/otp_01JD3W8K2Q9F7T6Y5X4V3B2N1M -H "Authorization: Bearer $MOTION5_KEY"The OTP object
{
"object": "otp",
"id": "otp_01JD3W8K2Q9F7T6Y5X4V3B2N1M",
"phone": "+234803••••567",
"purpose": "login",
"status": "pending",
"delivery": "delivered",
"attempts": 0,
"max_attempts": 5,
"channel": "whatsapp",
"mode": "live",
"created_at": "2026-11-16T09:30:00.000Z",
"expires_at": "2026-11-16T09:40:00.000Z",
"delivered_at": "2026-11-16T09:30:02.114Z",
"read_at": null,
"verified_at": null
}statuspending (can be checked), verified, expired, failed (too many tries, or never delivered) or cancelled (a newer code replaced it).deliverynot_sent, sent (WhatsApp accepted it), delivered (it reached the phone), read (the customer opened the chat) or failed (WhatsApp couldn't deliver it).attemptsmax_attempts.modelive or test, from the key that sent it.delivered_at, read_at, verified_atLimits
- Five tries per code. After that the code stops working.
- 30 seconds between codes to the same number (
429 too_soon), and at most 3 codes in 10 minutes per number (429 rate_limited). Both carryRetry-After. - A new code cancels the previous one, so only the latest code works.
Events
With a webhook endpoint, your server hears about each code without polling. Each event's data.otp is the OTP object.
otp.deliveredotp.readotp.faileddata.reason is undeliverable (WhatsApp couldn't reach the number), send_failed (WhatsApp refused it) or too_many_attempts.otp.verifiedIf a code doesn't arrive
Some numbers aren't on WhatsApp. When you get otp.failed with reason undeliverable (or GET /otp/{id} shows delivery: "failed"), offer the customer another way to get a code, such as SMS from your current provider.