POST /v3/verify — Verify a User-Submitted OTP Code

Use POST /v3/verify to check the code your user entered against an existing OTP transaction. Submit the otp_id from the original POST /v3/request or POST /v3/send response alongside the code the user provided. OTP.ID records the attempt and returns whether the code matched. A wrong code is not an HTTP error — read data.verified in the response body to determine the outcome.

Endpoint

POST https://api.otp.id/v3/verify

Request Headers

Header	Value	Required
`Authorization`	`Bearer <api_key>`	✅ Yes
`Content-Type`	`application/json`	✅ Yes

Request Body

string

required

The transaction ID returned by POST /v3/request or POST /v3/send. Format: OTP + YYYYMMDD + 4 letters + 6 digits (e.g. "OTP20260807ABCD000001").

string

required

The code submitted by the user. Pass it exactly as entered — OTP.ID compares it against the transaction’s stored code.

Response Fields

string

The transaction ID, echoed from your request.

boolean

true — the code matched; the transaction is now permanently marked as used
false — the code did not match; the attempt has been recorded against the transaction’s attempt counter

string

Human-readable reason string.

"" (empty string) — verification was successful
"mismatch" — the code the user entered did not match

Example

curl -X POST https://api.otp.id/v3/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"otp_id": "OTP20260807ABCD000001", "otp": "482913"}'

Response Scenarios

A code mismatch returns HTTP 200, not HTTP 4xx. Always check data.verified in your code — do not use the HTTP status code to detect a wrong code. A verified: false response still counts as an attempt.

Success — correct code

{
  "success": true,
  "data": {
    "otp_id": "OTP20260807ABCD000001",
    "verified": true,
    "reason": ""
  },
  "error": null
}

Mismatch — wrong code (HTTP 200)

{
  "success": true,
  "data": {
    "otp_id": "OTP20260807ABCD000001",
    "verified": false,
    "reason": "mismatch"
  },
  "error": null
}

Expired — OTP past its TTL (HTTP 422)

{
  "success": false,
  "data": null,
  "error": {
    "code": "OTP_EXPIRED",
    "message": "OTP sudah kedaluwarsa"
  }
}

Too many attempts (HTTP 422)

{
  "success": false,
  "data": null,
  "error": {
    "code": "TOO_MANY_ATTEMPTS",
    "message": "Percobaan verifikasi melebihi batas"
  }
}

Already used (HTTP 422)

{
  "success": false,
  "data": null,
  "error": {
    "code": "ALREADY_USED",
    "message": "OTP sudah pernah diverifikasi"
  }
}

Error Codes

All errors follow the shape {"success": false, "data": null, "error": {"code": "...", "message": "..."}}.

HTTP Status	Error Code	Description
400	`VALIDATION_ERROR`	A required field is missing or malformed (e.g. `otp_id` or `otp` not provided).
401	`UNAUTHORIZED`	The `Authorization` header is missing or the API key is invalid.
404	`OTP_NOT_FOUND`	No transaction with the given `otp_id` exists, or it belongs to a different merchant.
422	`OTP_EXPIRED`	The OTP’s TTL has elapsed. Issue a new OTP if the user needs to retry.
422	`TOO_MANY_ATTEMPTS`	The transaction has reached the maximum number of failed attempts (5). It is now locked.
422	`ALREADY_USED`	The OTP was already verified successfully and cannot be reused.
429	`RATE_LIMITED`	You have exceeded the API-level request rate limit.
500	`INTERNAL_ERROR`	An unexpected server-side error occurred.

Webhooks

A successful verification (where verified returns true) also triggers the otp.verified webhook asynchronously. Your server receives the event after OTP.ID records the verification — implement the webhook to react to verifications server-to-server without polling.

After a transaction reaches TOO_MANY_ATTEMPTS, subsequent verify calls for that otp_id will continue to return TOO_MANY_ATTEMPTS — the lock is permanent. You must start a new OTP transaction.

​Endpoint

​Request Headers

​Request Body

​Response Fields

​Example

​Response Scenarios

​Success — correct code

​Mismatch — wrong code (HTTP 200)

​Expired — OTP past its TTL (HTTP 422)

​Too many attempts (HTTP 422)

​Already used (HTTP 422)

​Error Codes

​Webhooks

Endpoint

Request Headers

Request Body

Response Fields

Example

Response Scenarios

Success — correct code

Mismatch — wrong code (HTTP 200)

Expired — OTP past its TTL (HTTP 422)

Too many attempts (HTTP 422)

Already used (HTTP 422)

Error Codes

Webhooks