Verification code statuses: pending, verified, expired, failed and cancelled

The short answer: every code has a status, returned in the status field of every response: pending (waiting), verified (confirmed), expired (out of time), failed (no attempts left) or cancelled (cancelled or replaced). Only a pending code can still give valid: true. The status also tells your system what to offer next.

The five statuses

Status	Means	What to do next
pending	The code went out and is still valid	Wait for the customer to type it; you can resend or cancel
verified	The customer typed the right code	Carry on. The same code will not work a second time
expired	The expires_in time has passed	Resend with /resend or request a new code
failed	No attempts left	Request a new code with POST /v1/sms/otp
cancelled	A newer code went to the same number, or it was cancelled	Use the most recent code, or request a new one

What each operation accepts

Operation	Works with	In other statuses
/verify	Any status; only pending can give valid: true	Always answers valid: false
/resend	pending and expired	The API refuses: request a new code
/cancel	pending	There is nothing to cancel
GET /v1/sms/otp/{id}	Any status	Shows the status, never the code

The fields that come with the status

1	attempts and attempts_left: wrong attempts used and attempts remaining. Show attempts_left to the customer after each mistake.

2	expires_at: when the code stops working, with the time zone. Use it for the countdown on screen.

3	verified_at: when it was confirmed, or empty. Keep it as a record.

4	resends: how many times the code was resent.

5	mode: whether the code was created in the Sandbox or in Production.

valid: false is not an API error. The check answers 200 even when the code is wrong; the valid field is what decides. A code that was already verified, has expired or has failed always answers valid: false, even if the customer types the right digits. HTTP errors (409, 422, 429) are covered in reading the verification API's answers.

To find out why it failed, read status together with valid. valid: false with pending is a typo (attempts remain); with expired it is too late; with failed the attempts ran out; with cancelled the customer typed an old code.

Want to follow each code from sending to confirmation? See Verification SMS.

See Verification SMS

Categories

Categories