API OTP WhatsApp: Kirim & Verifikasi Kode via OTP.ID

Kalau developer mencari “api otp whatsapp”, biasanya yang dibutuhkan bukan definisi OTP panjang. Yang dicari adalah jawaban praktis: endpoint mana yang dipanggil, payload-nya seperti apa, bagaimana cara verifikasi kode, dan apa yang harus dilakukan saat pengiriman gagal.

Artikel ini membahas alur API OTP WhatsApp memakai OTP.ID. Fokusnya integrasi backend: kirim kode ke WhatsApp End User, simpan otp_id, verifikasi kode, lalu siapkan error handling yang aman untuk produksi.

API OTP WhatsApp itu apa?

API OTP WhatsApp adalah API yang dipanggil backend aplikasi untuk mengirim kode verifikasi lewat WhatsApp. Di sisi End User, hasilnya terlihat seperti pesan berisi kode. Di sisi aplikasi Client, alurnya tetap HTTP request dan response JSON.

Ada dua jalan besar untuk membangun alur seperti ini. Pertama, tim mengurus langsung WhatsApp Business Platform: setup akun, template authentication, provisioning, dan integrasi pengiriman. Meta memang mensyaratkan authentication template jika aplikasi memberi opsi menerima one-time password atau verification code lewat WhatsApp.

Jalan kedua adalah memakai layanan verifikasi seperti OTP.ID. Client cukup memanggil API OTP.ID, sementara detail pengiriman, status transaksi, masa berlaku kode, batas percobaan, dan pencatatan biaya ditangani di sisi OTP.ID.

Ilustrasi API OTP WhatsApp yang menghubungkan backend aplikasi dengan smartphone verifikasi

Endpoint kirim OTP: `POST /v3/request`

Untuk integrasi awal, endpoint yang paling umum dipakai adalah POST /v3/request. Di mode ini, kode OTP dibuat oleh OTP.ID. Client tidak perlu membuat kode sendiri, tidak perlu menyimpan kode mentah, dan tidak perlu menulis sendiri aturan masa berlaku atau batas percobaan.

Base URL produksi OTP.ID adalah:

https://api.otp.id

Contoh request:

curl -X POST https://api.otp.id/v3/request \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "destination": "628xxxxxxxxxx",
    "brand": "TokoAnda",
    "otp_length": 6,
    "ttl": 300,
    "external_id": "register-1042"
  }'

Field yang wajib diperhatikan:

Field	Fungsi
`channel`	Isi `"whatsapp"` untuk mengirim OTP lewat WhatsApp.
`destination`	Nomor HP tujuan, digit saja, format internasional tanpa tanda plus.
`brand`	Nama brand yang ditampilkan di pesan berbasis chat.
`otp_length`	Panjang kode; default 6, dibatasi 4–8.
`ttl`	Masa berlaku dalam detik; default 300, dibatasi 60–900.
`external_id`	ID dari sistem Client untuk idempotency dan pelacakan.

Response sukses berisi otp_id. Simpan nilai ini di database aplikasi karena akan dipakai saat verifikasi.

{
  "success": true,
  "data": {
    "otp_id": "OTP20260816ABCD000123",
    "status": "sent",
    "channel": "whatsapp",
    "number": "628xxxxxxxxxx",
    "price": 370,
    "last_balance": 9630,
    "expires_at": "2026-08-16 10:05:00"
  },
  "error": null
}

price dan last_balance adalah informasi biaya request dan sisa kredit prepaid. Angka di atas hanya contoh bentuk response; harga publik yang berlaku mengikuti katalog harga dan dashboard.

Satu detail penting: gagal kirim ke vendor tetap bisa kembali sebagai HTTP 200, tetapi data.status bernilai "failed". Pada kondisi ini saldo tidak dipotong. Jadi jangan berhenti di pengecekan HTTP status saja; selalu baca data.status.

Verifikasi kode: `POST /v3/verify`

Setelah End User menerima kode dan mengisinya di aplikasi, backend Client memanggil endpoint verifikasi.

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

Perilaku response-nya sengaja dibedakan antara kode salah dan error final:

Kondisi	HTTP	Response
Kode benar	200	`verified: true`
Kode salah	200	`verified: false`, `reason: "mismatch"`
Kode kedaluwarsa	422	`OTP_EXPIRED`
Terlalu banyak percobaan	422	`TOO_MANY_ATTEMPTS`
Sudah pernah dipakai	422	`ALREADY_USED`

Kode salah bukan exception. Perlakukan verified:false sebagai respons normal dan tampilkan pesan yang jelas di UI, misalnya “kode salah, coba lagi”. Exception handler lebih cocok untuk kondisi seperti UNAUTHORIZED, INSUFFICIENT_BALANCE, atau rate limit.

Kapan pakai `request`, kapan pakai `send`?

OTP.ID punya dua mode pengiriman:

POST /v3/request: kode OTP dibuat oleh OTP.ID.
POST /v3/send: kode OTP dibuat oleh Client, lalu OTP.ID mengirimkannya.

Untuk kebanyakan integrasi baru, mulai dari request. Mode ini memindahkan pekerjaan rawan salah ke server OTP.ID: pembuatan kode, TTL, hashing, batas percobaan, dan sekali-pakai. Mode send lebih cocok jika aplikasi sudah punya sistem OTP sendiri dan hanya butuh channel pengiriman.

Pada V3, channel whatsapp, sms, dan email mendukung request maupun send. Missed Call dan WhatsApp inbound memakai request karena cara verifikasinya berbeda.

Proteksi produksi yang jangan dilewatkan

API yang terlihat sederhana tetap butuh pagar di sekitar alur registrasi atau login. Di OTP.ID, beberapa pagar sudah berjalan di server: TTL, maksimal percobaan, sekali-pakai, rate limit per API key, dan rate limit per nomor tujuan.

Gunakan external_id untuk mencegah double-send saat retry jaringan. Jika request dengan external_id dan parameter yang sama diulang dalam 24 jam, server mengembalikan response pertama tanpa kirim ulang dan tanpa debit ulang. Kalau external_id sama dipakai dengan parameter berbeda, response-nya 409 DUPLICATE_EXTERNAL_ID.

Ilustrasi proteksi API OTP WhatsApp dengan perisai, gembok, dan jalur request

Di sisi aplikasi Client, tetap lakukan hal-hal ini:

simpan API key hanya di backend, bukan di aplikasi mobile atau frontend;
jangan tulis kode OTP ke log, analytics, atau error tracker;
beri cooldown pada tombol “kirim ulang”;
normalisasi nomor ke format digit dengan awalan negara;
pantau last_balance dan aktifkan balance alert di dashboard.

OTP.ID tidak menyediakan sandbox terpisah. Untuk uji awal, gunakan nomor tim sendiri dan siapkan skenario gagal, termasuk nomor yang tidak terdaftar di WhatsApp.

Kalau WhatsApp gagal terkirim

Jika nomor tidak bisa menerima WhatsApp, response request dapat berisi status: "failed" dan saldo tidak didebit. OTP.ID tidak melakukan fallback otomatis antar-channel. Keputusan channel berikutnya tetap ada di aplikasi Client.

Pola yang aman: tampilkan opsi ke End User, misalnya “kirim lewat SMS” atau “gunakan Missed Call”. Setelah End User memilih, backend membuat request baru dengan channel berbeda, misalnya "sms", "misscall", "voice", atau "email".

Pendekatan ini membuat biaya dan pengalaman pengguna lebih mudah dikendalikan. Client tidak kaget karena sistem diam-diam mencoba channel lain, dan End User tetap diberi pilihan yang sesuai konteks.

Biaya API OTP WhatsApp dan mulai integrasi

OTP.ID memakai model prepaid pay-per-OTP. Harga publik WhatsApp bergantung pada produk/channel yang dipakai; katalog landing menampilkan WhatsApp mulai Rp120 per OTP untuk Tap-to-Verify, dengan varian WhatsApp lain mengikuti katalog harga publik.

Untuk mulai mencoba, buat akun di [app.otp.id](https://app.otp.id). Merchant baru mendapat kredit gratis Rp2.000 untuk testing awal. Setelah itu, ambil API key dari dashboard, panggil POST /v3/request, lalu sambungkan response otp_id ke POST /v3/verify.

Kalau butuh referensi lebih detail, dokumentasi API tersedia di [docs.otp.id](https://docs.otp.id). Untuk pembahasan alur request → verify yang lebih naratif, baca juga artikel [Verifikasi Nomor HP dengan WhatsApp OTP](https://otp.id/blog/verifikasi-nomor-hp-dengan-whatsapp-otp-alur-request-verify-untuk-developer).