Verification lifecycle
What happens to a code from sending to approval, expiry or failure, and how resending works.
Statuses
send
│
▼
┌────────┐ right code ┌──────────┐
│pending │─────────────▶│ approved │
└────────┘ └──────────┘
time runs out │ │ 5 wrong tries a newer code to the same number
▼ ▼ │
┌────────┐ ┌────────┐ ┌──────────┐
│expired │ │ failed │ │ canceled │
└────────┘ └────────┘ └──────────┘| Status | Meaning | What to show the customer |
|---|---|---|
pending | Waiting for the code | The code box |
approved | The right code was checked | Continue |
expired | Not checked in time | "The code expired, ask for a new one" |
failed | 5 wrong tries, or the message couldn't be sent | "Ask for a new code" |
canceled | Replaced by a newer code to the same number | Use the newest code |
Rules
- Code: 4 digits, or 6 if you choose so in your settings.
- Valid for: 5 minutes by default; you can choose 1 to 15 minutes in your settings.
expires_atgives the exact time. - Tries: 5 checks per code, counted before the code is compared, so parallel guesses can't go past the limit.
attempts_lefttells you how many remain. - Single use:
valid: truecomes back once, on the check that approved the code. Later checks answervalid: falsewith statusapproved. This stops replays: always act onvalid, never onstatusalone. - One code per number at a time: sending a new code to the same number cancels the previous one (per key mode).
- Customer input: spaces and Arabic-Indic digits (
٤٨٢١) are accepted incode.
Resending
There is no separate resend endpoint: sending again is the resend. Limits apply: per number: one code every 30 seconds, 5 an hour and 10 a day; per account: 120 codes a minute (test and live keys are counted separately). Show a countdown of 30 seconds after each send, and disable the button while a request is in flight so a double click can't send (and charge) twice. A 429 rate_limited answer says how long to wait in retry_after.
Checking by phone number
Instead of id, /verify/check accepts phone and checks the latest code sent to that number with the same key mode. Prefer id: it can't pick up a different, newer code.
Delivery
OTP.ps hands the message to the gateway and knows whether it was accepted or refused (502 sms_failed, nothing charged). It does not receive delivery reports from the networks, so there is no "delivered" status. If a customer says they got nothing, let them resend after the cooldown and double-check the number.