WhatsApp OTP integration

Use this guide when you want OTP.ID to send an outbound WhatsApp message that contains a one-time password. Send channel: "whatsapp" to POST /v3/request or POST /v3/send, show an OTP input in your application, then verify the code with POST /v3/verify. WhatsApp OTP is a good default when your users are active on WhatsApp. The user receives a readable chat message, copies the code, and enters it in your app.

Flow overview

Create the OTP transaction

Use POST /v3/request when OTP.ID should generate the code, or POST /v3/send when your backend already generated the code.

OTP.ID sends the WhatsApp message

OTP.ID delivers the OTP to the destination phone number in international digits-only format.

Show your OTP input

Ask the user to enter the code from WhatsApp. Keep the expiry time and resend action visible.

Verify the submitted code

Call POST /v3/verify with the otp_id from the send response and the code entered by the user.

Continue only when verified

Treat data.verified: true as success. A wrong code returns HTTP 200 with data.verified: false.

Option A: OTP.ID generates the code

Use POST /v3/request when your server does not need to know the OTP value. This is the recommended path for most integrations because the code is never exposed to your backend.

Request

curl -X POST https://api.otp.id/v3/request \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "destination": "6281234567890",
    "brand": "TokoKita",
    "otp_length": 6
  }'

Success response

Save data.otp_id. You need it when the user submits the code.

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811ABCD000001",
    "status": "sent",
    "channel": "whatsapp",
    "number": "6281234567890",
    "price": 350,
    "last_balance": 99650,
    "expires_at": "2026-08-11 10:05:00"
  },
  "error": null
}

The generated OTP code is not returned by the API. OTP.ID sends it only through WhatsApp.

Option B: You provide the code

Use POST /v3/send when your backend must generate and own the OTP code.

Request

curl -X POST https://api.otp.id/v3/send \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "destination": "6281234567890",
    "otp": "482913",
    "brand": "TokoKita"
  }'

Success response

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811ABCD000002",
    "status": "sent",
    "channel": "whatsapp",
    "number": "6281234567890",
    "price": 350,
    "last_balance": 99300,
    "expires_at": "2026-08-11 10:05:00"
  },
  "error": null
}

Verify the WhatsApp OTP

When the user enters the WhatsApp code, submit it with the original otp_id.

Request

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

Correct code response

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

Wrong code response

Wrong codes return HTTP 200. Always check data.verified.

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

Terminal error example

When the OTP expires, is already used, or reaches the failed-attempt limit, OTP.ID returns HTTP 422.

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

UI recommendations

Show copy such as “Enter the code we sent to your WhatsApp.”
Use a single OTP input or six separated digit boxes.
Support paste, auto-advance, and backspace navigation.
Show the expiry time from expires_at.
Disable Resend code until your own cooldown finishes.
If status is "failed", tell the user to request a new OTP or choose another channel.
If verification returns verified: false, let the user retry while attempts remain.

Get Started

Core Concepts

Channel Guides

Guides

Reference

WhatsApp OTP integration

Flow overview

Option A: OTP.ID generates the code

Request

Success response

Option B: You provide the code

Request

Success response

Verify the WhatsApp OTP

Request

Correct code response

Wrong code response

Terminal error example

UI recommendations

​Flow overview

​Option A: OTP.ID generates the code

​Request

​Success response

​Option B: You provide the code

​Request

​Success response

​Verify the WhatsApp OTP

​Request

​Correct code response

​Wrong code response

​Terminal error example

​UI recommendations

​Related pages

Flow overview

Option A: OTP.ID generates the code

Request

Success response

Option B: You provide the code

Request

Success response

Verify the WhatsApp OTP

Request

Correct code response

Wrong code response

Terminal error example

UI recommendations

Related pages