Getting started

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 │
          └────────┘ └────────┘            └──────────┘
StatusMeaningWhat to show the customer
pendingWaiting for the codeThe code box
approvedThe right code was checkedContinue
expiredNot checked in time"The code expired, ask for a new one"
failed5 wrong tries, or the message couldn't be sent"Ask for a new code"
canceledReplaced by a newer code to the same numberUse 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_at gives the exact time.
  • Tries: 5 checks per code, counted before the code is compared, so parallel guesses can't go past the limit. attempts_left tells you how many remain.
  • Single use: valid: true comes back once, on the check that approved the code. Later checks answer valid: false with status approved. This stops replays: always act on valid, never on status alone.
  • 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 in code.

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.

View as Markdown