OTP Transaction Lifecycle, Statuses, and Expiry Rules

Every OTP you create in OTP.ID is a transaction with its own unique identifier, status, and expiry window. Understanding the lifecycle of that transaction — from the moment you call the API to the moment the OTP is verified or expires — helps you build reliable, user-friendly authentication flows. This page walks through each stage in order, explains the status values you will encounter, and documents the clamping rules that govern TTL and OTP length.

OTP Transaction ID Format

Every OTP transaction is assigned a unique ID at creation time. The format is:

OTP + YYYYMMDD + 4 random uppercase letters + 6-digit daily counter

Example: OTP20260807ABCD000001

Segment	Example	Description
Prefix	`OTP`	Fixed string
Date	`20260807`	Creation date (WIB, UTC+7) in `YYYYMMDD` format
Random suffix	`ABCD`	4 randomly generated uppercase letters
Daily counter	`000001`	Sequential counter, resets each day (WIB)

Store the otp_id returned in the API response — you need it to poll the transaction status and to verify the OTP.

Transaction Statuses

The status field of a transaction takes one of the following values.

Status	Meaning	Terminal?
`pending`	Awaiting completion. Always the initial status for `whatsapp_inbound` (the user has not yet replied); may also appear for some delivery vendors.	No
`sent` / `success`	The OTP was successfully delivered to the channel vendor. Credits are deducted at this point.	No (can still be verified or expire)
`failed`	The vendor could not deliver the OTP. Credits are not deducted. The HTTP response is still `200 OK`.	Yes
`verified`	The OTP was successfully verified (correct code submitted, or matching WhatsApp inbound message received).	Yes

A failed delivery still creates a transaction record and still returns HTTP 200 OK. Check the status field in the response body to distinguish a failed delivery from a network or authentication error.

Expiry and attempt exhaustion are not status values. When the TTL elapses or the channel-specific attempt limit is reached, the stored status does not change (it stays sent/success) — instead, POST /v3/verify rejects the attempt with error code OTP_EXPIRED, TOO_MANY_ATTEMPTS, or ALREADY_USED (HTTP 422). The failed-attempt limit is 5 for standard channels and 2 for misscall. Use expires_at and attempts from GET /v3/otp/{otp_id} to detect these conditions when polling.

Lifecycle Flow

The diagram below describes the full journey of an OTP transaction in plain text.

[Your Server]
     │
     │  POST /v3/request  or  POST /v3/send
     ▼
[OTP.ID API]  ──calls channel vendor synchronously──►
     │
     ├── Delivery succeeds ──►  status: sent / success   (returned in the API response)
     │                              │
     │                              │  User receives OTP
     │                              │
     │                              ▼
     │                         POST /v3/verify
     │                              │
     │                              ├── Code correct  ──►  status: verified  ✅
     │                              │
     │                              ├── Code wrong (attempts below channel limit)  ──►  status unchanged,
     │                              │        HTTP 200, verified: false, reason: "mismatch"
     │                              │
     │                              ├── Attempts exhausted  ──►  HTTP 422 TOO_MANY_ATTEMPTS  ❌
     │                              │        (status stays sent/success, permanently locked)
     │                              │
     │                              └── TTL exceeded  ──►  HTTP 422 OTP_EXPIRED  ❌
     │                                       (status stays sent/success)
     │
     └── Delivery fails  ──►  status: failed  ❌  (no credits deducted)

(whatsapp_inbound differs: the transaction is created with status: pending, no vendor
 call is made, and it advances to verified when the user's WhatsApp message arrives.)

Create the transaction

Call POST /v3/request (with automatic OTP generation or request-only flows) or POST /v3/send (supplying your own OTP value for whatsapp, sms, or email). Delivery happens synchronously — the API response already carries the delivery outcome (status: sent/success/failed) together with the otp_id. Only whatsapp_inbound starts at status: pending.For whatsapp_inbound, the response also includes a verification block containing wa_number, message, wa_link, and expires_at. Display this information to your user right away.

OTP.ID attempts delivery

OTP.ID contacts the channel vendor (WhatsApp provider, SMS gateway, email relay, or telephony provider). If the vendor accepts the message, the status advances to sent or success and credits are deducted. If the vendor rejects or cannot reach the destination, the status is set to failed and no charge is applied.

User receives the code

Your user reads the OTP from their WhatsApp message, SMS, email, missed-call log, or (for whatsapp_inbound) sends the pre-filled WhatsApp message. The OTP is valid until the TTL expires.

Your app submits the code for verification

When the user enters the code in your interface, call POST /v3/verify with the otp_id and the otp value the user provided.

{
  "otp_id": "OTP20260807ABCD000001",
  "otp": "482910"
}

OTP.ID returns the verification result

OTP.ID checks the submitted code and returns one of the following outcomes:

Correct code — HTTP 200, verified: true. Status advances to verified.
Wrong code (attempts remaining) — HTTP 200, verified: false, reason: "mismatch". The transaction remains active; the user can try again.
Attempt limit reached — the failed submission that reaches the limit returns HTTP 200 with verified: false; the transaction is then permanently locked. The next verification call returns HTTP 422 with TOO_MANY_ATTEMPTS. The limit is 5 failed attempts for standard channels and 2 for misscall.
Expired — HTTP 422, error code OTP_EXPIRED.
Already used — HTTP 422, error code ALREADY_USED.

Polling Transaction Status

If you need to check the state of a transaction outside of the verification flow (for example, to confirm delivery or to build a status dashboard), use the status endpoint:

GET /v3/otp/{otp_id}
Authorization: Bearer <api_key>

Example response:

{
  "success": true,
  "data": {
    "otp_id": "OTP20260807ABCD000001",
    "status": "sent",
    "channel": "whatsapp",
    "number": "6281234567890",
    "attempts": 0,
    "expires_at": "2026-08-07 10:05:00",
    "verified_at": "",
    "price": 350
  },
  "error": null
}

Poll this endpoint periodically for whatsapp_inbound transactions to detect when the user has sent their reply and the status advances to verified.

TTL Clamping

The ttl field controls how many seconds the OTP remains valid after creation. OTP.ID applies the following clamping rules silently — values outside the valid range are adjusted rather than rejected.

Input value	Effective TTL
Below 60	Clamped to 60 seconds
60 – 900	Used as-is
Above 900	Clamped to 900 seconds
Not provided	Defaults to 300 seconds

OTP.ID never returns a validation error for an out-of-range ttl. The value is silently clamped. Always read the expires_at field in the response to know the exact expiry time.

OTP Length Clamping

The otp_length field controls how many digits the generated OTP contains. The same silent clamping logic applies.

Input value	Effective length
Below 4	Clamped to 4 digits
4 – 8	Used as-is
Above 8	Clamped to 8 digits
Not provided	Defaults to 6 digits

Verification Behaviour Reference

Scenario	HTTP status	`verified`	`reason` / error code
Correct code	`200`	`true`	—
Wrong code while attempts remain	`200`	`false`	`"mismatch"`
Final wrong code that reaches the limit	`200`	`false`	`"mismatch"`
Verify after the attempt limit	`422`	—	`TOO_MANY_ATTEMPTS`
OTP expired	`422`	—	`OTP_EXPIRED`
OTP already verified	`422`	—	`ALREADY_USED`

A wrong-code response is not a server error — it is a successful API call that returns verified: false. Do not treat HTTP 200 with verified: false as an exception or retry it automatically. Show the user a “wrong code” message and let them try again while attempts remain. The limit is 5 failed attempts for standard channels and 2 for misscall.

Build your verification UI to count remaining attempts on the client side. For standard channels, warn the user after 4 failed attempts; for Missed Call, warn after the first failed attempt because one attempt remains. You can also request a new OTP at any time if the user wants to start fresh, subject to the request rate limit for that channel.

Get Started

Core Concepts

Channel Guides

Guides

Reference

OTP Transaction Lifecycle, Statuses, and Expiry Rules

OTP Transaction ID Format

Transaction Statuses

Lifecycle Flow

Polling Transaction Status

TTL Clamping

OTP Length Clamping

Verification Behaviour Reference

​OTP Transaction ID Format

​Transaction Statuses

​Lifecycle Flow

​Polling Transaction Status

​TTL Clamping

​OTP Length Clamping

​Verification Behaviour Reference

OTP Transaction ID Format

Transaction Statuses

Lifecycle Flow

Polling Transaction Status

TTL Clamping

OTP Length Clamping

Verification Behaviour Reference