# Verification lifecycle

> What happens to a code from sending to approval, expiry or failure, and how resending works.

## Statuses

```text
                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_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.
