Voice OTP integration

Use Voice when you want OTP.ID to call a user and read an OTP aloud. Your merchant’s Voice channel must be active before you request a Voice OTP. Voice is available only through POST /v3/request; it does not support POST /v3/send.

Flow overview

Create the Voice transaction

Send the destination phone number and an explicit brand to POST /v3/request with channel: "voice".

Tell the user to listen for the call

OTP.ID places a call and reads the brand followed by the four OTP digits one at a time.

Verify the entered code

Collect the four digits from the user and call POST /v3/verify with the otp_id returned by the request.

Create a Voice OTP

Send the phone number as digits only in international format beginning with 62. brand is required. Voice always uses four numeric digits, even if you include otp_length in the request.

Request

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

Success response

Save data.otp_id. You need it when the user submits the four digits they heard during the call.

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811VOIC000001",
    "status": "sent",
    "channel": "voice",
    "number": "6281234567890",
    "price": 450,
    "last_balance": 99550,
    "expires_at": "2026-08-11 10:05:00"
  },
  "error": null
}

The call follows this spoken pattern, with each OTP digit read separately:

Kode TokoKita 1 6 7 8

Use data.otp_id from the normal V3 response for verification. The request response does not confirm that the user answered the call or the final delivery cost.

Verify the Voice OTP

Use the ordinary V3 verification flow. Submit the four digits the user heard; do not generate or supply the Voice OTP yourself.

Request

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

Correct code response

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

Wrong code response

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

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811VOIC000001",
    "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"
  }
}

Troubleshooting

`CHANNEL_UNAVAILABLE`

Voice is not active for your merchant or is temporarily unavailable. Confirm that your merchant Voice channel has been activated, then retry the request later if the channel is temporarily unavailable.

Request returns `status: "failed"`

The delivery provider could not complete the request. Read data.failure.code and data.failure.message for the specific reason (typically PROVIDER_UNAVAILABLE or DELIVERY_FAILED for Voice) — see the failure reason reference. Check that the destination number is a valid reachable phone number in 62... format, then let the user retry or use another available channel. Do not treat a request response as confirmation that the user answered the call.

The user did not receive or understand the code

Ask the user to listen for the call again through a new OTP request after the current OTP expires or is no longer usable. The code is always four numeric digits and is read one digit at a time.

Get Started

Core Concepts

Channel Guides

Guides

Reference

Voice OTP integration

Flow overview

Create a Voice OTP

Request

Success response

Verify the Voice OTP

Request

Correct code response

Wrong code response

Terminal error example

Troubleshooting

`CHANNEL_UNAVAILABLE`

Request returns `status: "failed"`

The user did not receive or understand the code

​Flow overview

​Create a Voice OTP

​Request

​Success response

​Verify the Voice OTP

​Request

​Correct code response

​Wrong code response

​Terminal error example

​Troubleshooting

​CHANNEL_UNAVAILABLE

​Request returns status: "failed"

​The user did not receive or understand the code

Flow overview

Create a Voice OTP

Request

Success response

Verify the Voice OTP

Request

Correct code response

Wrong code response

Terminal error example

Troubleshooting

`CHANNEL_UNAVAILABLE`

Request returns `status: "failed"`

The user did not receive or understand the code