Motion 5Book a demo

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

  1. Your server calls POST /otp/send with the customer's phone number and gets back an id.
  2. 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."
  3. Your app asks for the code, and your server calls POST /otp/verify with the id and 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.

POST/v1/otp/send
Send a new code to a phone number. A new code cancels any earlier code for that number that hasn't been used.

Body

phone
stringrequired
The customer's WhatsApp number: 08031234567, +2348031234567 or another country's number in international form.
purpose
stringoptional
Your label, up to 40 characters, such as login or transfer. Shown in Developers and in events.
ttl_seconds
integeroptional
How long the code works, from 60 to 900. Default 600 (10 minutes).
length
integeroptional
Digits in the code, from 4 to 8. Default 6.
curl https://motion-5-delta.vercel.app/api/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

WhatsApp's code message always says the code expires in 10 minutes. If you choose a different ttl_seconds, tell the customer the real time in your app.
POST/v1/otp/verify
Check the code a customer typed. Each check counts as a try, even if it fails, so call it only with what the customer actually entered.

Body

id
stringrequired
The id from /otp/send.
code
stringrequired
The digits the customer typed. Spaces around it are ignored.
Responses
{ "valid": true }

{ "valid": false, "reason": "wrong_code", "attempts_left": 3 }
{ "valid": false, "reason": "expired" }

Reasons

wrong_code
Not the right code. attempts_left says how many tries remain.
expired
The code's time ran out. Send a new one.
too_many_attempts
Five wrong tries: the code no longer works. Send a new one.
already_used
This code was already verified. Each code works once.
cancelled
A newer code was sent to the same number. Ask for the newest one.
failed
The code was never delivered (WhatsApp couldn't reach the number).

An unknown id, or one from the other mode, gets 404 not_found.

GET/v1/otp/{id}
Look up a code: whether it's still usable and how far WhatsApp got with it. Useful for showing "Code sent" or "Didn't get it?" in your app.
Example
curl https://motion-5-delta.vercel.app/api/v1/otp/otp_01JD3W8K2Q9F7T6Y5X4V3B2N1M -H "Authorization: Bearer $MOTION5_KEY"

The OTP object

otp
{
  "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
}
status
string
pending (can be checked), verified, expired, failed (too many tries, or never delivered) or cancelled (a newer code replaced it).
delivery
string
not_sent, sent (WhatsApp accepted it), delivered (it reached the phone), read (the customer opened the chat) or failed (WhatsApp couldn't deliver it).
attempts
integer
Checks so far, out of max_attempts.
mode
string
live or test, from the key that sent it.
delivered_at, read_at, verified_at
time or null
When each step happened.

Limits

  • 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 carry Retry-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.delivered
event
The code reached the customer's phone. Test codes raise this at once.
otp.read
event
The customer opened the chat with the code.
otp.failed
event
The code can't be used. data.reason is undeliverable (WhatsApp couldn't reach the number), send_failed (WhatsApp refused it) or too_many_attempts.
otp.verified
event
The code was checked and matched.

If 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.