Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

OTP & Notifikasi WA

Layanan One-Time Password (OTP) dan notifikasi transaksi DagangBot dirancang sebagai jembatan komunikasi dua arah yang sangat andal antara merchant dan pelanggan. Sistem ini tidak hanya memfasilitasi pembuatan kode keamanan acak dan kedaluwarsa singkat untuk autentikasi, tetapi juga menyajikan infrastruktur pengiriman melalui kanal primer WhatsApp dengan cadangan SMS (fallback). Semua dikendalikan melalui sistem antrean yang dapat diandalkan dan dikawal oleh pembatas lalu lintas jaringan (rate limiter) yang ketat.

Modul ini menjawab masalah umum dalam pengiriman OTP: keterlambatan pesan, eksploitasi oleh bot (OTP pumping), dan biaya pengiriman yang melonjak akibat percobaan palsu. Dengan menyatukan logika pembuatan CSPRNG (Cryptographically Secure Pseudo-Random Number Generator), pengiriman adaptif, dan verifikasi hash-based (HMAC-SHA256) di tingkat server, modul OTP menjaga keseimbangan antara keamanan, pengalaman pengguna, dan margin operasional.

1. Ikhtisar & Nilai Bisnis

Infrastruktur OTP platform memberikan perlindungan menyeluruh melalui manajemen percobaan pengiriman (rate limiting) dan arsitektur pengiriman tangguh. Berikut adalah pilar utama nilai bisnis yang dihasilkan:

  • Pengiriman Kanal Ganda (Multi-Channel Routing): Sistem memprioritaskan WhatsApp sebagai kanal utama yang bebas biaya tambahan di luar tagihan Meta, namun secara mulus beralih ke penyedia SMS pihak ketiga (seperti Zenziva) dalam milidetik apabila koneksi ke Meta mengalami gangguan. Hal ini memastikan OTP tetap terkirim saat kritis.
  • Pencegahan Penyedotan Biaya (Anti-OTP Pumping): Lapisan pembatas rate limit berbasis Redis mengunci percobaan berdasarkan kombinasi nomor telepon, identitas penyewa (merchant), dan batasan harian global. Ini melindungi sistem dari bot yang mencoba menghabiskan anggaran SMS dengan meminta kode secara massal.
  • Personalisasi Template Pesan: Menyediakan templat dinamis di mana penyewa dapat memasukkan variabel seperti nama jenama, kode OTP, dan batas waktu kedaluwarsa (misalnya: {{brand_name}}). Ini menjaga profesionalisme serta kewaspadaan pengguna.
  • Verifikasi Kriptografis Tanpa Bocor: Semua kode OTP tidak pernah disimpan dalam format teks polos. Basis data otp_requests hanya menyimpan hash dari kode yang dibentuk bersama salt spesifik (merchant, nomor telepon, dan secret kunci), mencegah penyalahgunaan internal.
Prioritas Keamanan Kanal

Meskipun pengiriman OTP dialihkan ke SMS saat WhatsApp mengalami interupsi, biaya SMS akan memotong saldo kredit (token) penyewa secara proporsional. Selalu anjurkan pelanggan Anda memakai nomor WhatsApp yang aktif untuk meminimalisasi pengurangan saldo.

Penerapan standar ini membantu penyewa mempertahankan operasional bisnis tanpa kekhawatiran terhadap lonjakan tagihan komunikasi yang tidak wajar.

2. Alur Visual & Antarmuka

Layar antarmuka dasbor OTP memberi penyewa visibilitas penuh terhadap performa kanal komunikasi WhatsApp, sisa kuota, serta riwayat pengiriman kode verifikasi. Melalui konsol OTP (/app/otp), admin dapat langsung menguji coba pengiriman OTP ke nomor ponsel tertentu, memeriksa log pengiriman real-time, dan mengaudit status verifikasi:

Dasbor layanan OTP WhatsApp DagangBot dengan metrik kuota dan riwayat pengiriman
Dasbor layanan OTP WhatsApp terpadu dengan metrik kuota token, formulir uji kirim, dan tabel status verifikasi.

Tampilan laporan metrik juga memisahkan persentase antara pesan terkirim, gagal dalam rute utama, dan terkirim pada rute cadangan, yang memudahkan penyewa mengevaluasi keandalan nomor pelanggan mereka.

3. Panduan Langkah-demi-Langkah

Untuk menerapkan sistem OTP yang dilindungi sepenuhnya pada proses pendaftaran aplikasi pihak ketiga (seperti headless merchant app), ikuti urutan berikut:

  1. 1

    Langkah 1: Registrasi dan Konfigurasi Template

    Buka modul konfigurasi di dasbor dan navigasi ke menu Komunikasi → Template OTP. Buat templat baru menggunakan bahasa yang ramah pelanggan namun formal. Pastikan variabel wajib, yaitu {{otp_code}}, disertakan dalam rancangan pesan Anda. Pilih apakah SMS akan diizinkan sebagai kanal cadangan (fallback) apabila gagal ke WhatsApp.

  2. 2

    Langkah 2: Permintaan Kode (Send)

    Ketika pelanggan memasukkan nomor ponsel di aplikasi klien Anda, klien memanggil endpoint POST /api/v1/otp/send. Pastikan untuk meneruskan nomor telepon tanpa kode negara + (disarankan memakai kanonik 62...). Sistem kemudian menghasilkan kode acak dengan durasi kedaluwarsa bawaan.

  3. 3

    Langkah 3: Penanganan Respons Rate Limit

    Pada klien aplikasi Anda, antisipasi status 429 Too Many Requests. Sistem mengenakan masa tunggu (cooldown) antara permintaan dari nomor yang sama. Berikan indikator visual (timer mundur) selama 60 detik kepada pelanggan, agar mereka tidak secara panik menekan tombol kirim ulang.

  4. 4

    Langkah 4: Pengumpulan dan Verifikasi (Verify)

    Sediakan kolom 6 angka bagi pelanggan untuk memasukkan OTP. Kirim nilai yang dimasukkan ke POST /api/v1/otp/verify. Sistem akan membandingkan masukan dengan rekam jejak (hash) di basis data.

  5. 5

    Langkah 5: Penanganan Penguncian Sementara

    Apabila pelanggan salah memasukkan kode melebihi batas (secara default, 3 kali berturut-turut), respons API akan berisi alasan locked. Aplikasi harus memblokir percobaan selama 10 menit. Tampilkan pesan peringatan demi keamanan akun dan minta pelanggan mencoba beberapa saat lagi.

4. Parameter & Spesifikasi Teknis

Sistem menggunakan kontrol granular pada pengiriman, memvalidasi rentang waktu secara ketat melalui implementasi Redis Rate Limiter dan memonitor status pengiriman di tabel otp_requests.

Parameter Pembatas Nilai Standar Logika Verifikasi & Penanganan di Tingkat API
Kunci Pendingin (Cooldown) 60 Detik Kunci Redis ratelimit:otp:cooldown:<merchant_id>:<phone> menolak pengiriman ulang (HTTP 429) hingga masa tunggu usai.
Batas per Merchant & Nomor 5 Pengiriman / Jam Mencegah pelanggan yang sama menerima kode berlebih dari 1 merchant (kunci ratelimit:otp:<merchant>:<phone>).
Anti-Pumping (Global) 15 Pengiriman / Hari Batas absolut untuk 1 nomor di seluruh jaringan (cross-merchant) ratelimit:otp:global:<phone>, memblokir bot skala besar.
Batas Harian per Tenant 500 OTP / Hari Kuota maksimum penyewa untuk mengirim OTP secara keseluruhan ratelimit:otp:tenant:<merchant>. Jika habis, seluruh fungsi OTP pada tenant tersebut terjeda.
Maksimal Percobaan Salah 3 Kali Kolom attempts pada tabel otp_requests. Jika mencapai max_attempts (3), status menjadi locked dan durasi pembekuan diaktivasi.
Durasi Penguncian (Lockout) 10 Menit Disimpan di lockout_until. Kolom ini memastikan semua upaya verifikasi ditolak dengan reason: "locked" meskipun kode mungkin benar.
Panjang Karakter & Kedaluwarsa 6 Digit & 5 Menit Kode OTP otpLength didukung 4, 6, dan 8 digit. Kolom expires_at membatalkan pending menjadi expired.

Siklus hidup status dalam otp_requests (kolom status):

  • pending: Menunggu diverifikasi.
  • verified: Berhasil diverifikasi. Hanya dapat dikonsumsi satu kali.
  • expired: Melewati batas waktu.
  • locked: Disalahgunakan (terlalu banyak attempts).

5. Relasi & Integrasi

Detail Mekanisme Rate Limiting (Pemblokiran Bertingkat)

Guna memberikan pelindungan maksimal terhadap upaya serangan pengurasan kuota, implementasi rate limiter dibagi ke dalam tiga lapis pelindung yang dievaluasi secara berurutan. Setiap kali ada permintaan POST /api/v1/otp/send, peladen memvalidasi metrik pada peladen in-memory (Redis) dengan urutan:

  1. Lapisan Cooldown (Jeda Waktu Sesaat) Ketika OTP diterbitkan, Redis langsung menulis key ratelimit:otp:cooldown:<merchant_id>:<phone> dengan parameter TTL (Time-to-Live) absolut 60 detik. Sebelum TTL ini habis, semua permintaan dari entitas ponsel tersebut akan secara instan ditolak di level pangkalan memori sehingga tidak membebani komputasi peladen aplikasi.
  2. Lapisan Batas Per Tenant-Ponsel (Hourly Limit) Setelah lolos pengecekan cooldown, sistem memeriksa akumulasi hitungan pada key ratelimit:otp:<merchant>:<phone>. Ambang batas diatur 5 kali per jam. Jika seorang pengguna asli sekalipun secara impulsif mencoba meminta pesan ulang, langkah ini mencegah penggunaan saluran melebihi 5 kali.
  3. Lapisan Anti-Pumping Universal (Global Hit) Sistem merekam setiap ponsel yang meminta OTP tanpa memedulikan merchant yang dihubungi lewat key ratelimit:otp:global:<phone>. Batas ketat ini disetel maksimal 15 permintaan per 24 jam. Hal ini merupakan pertahanan utama melawan gerombolan bot yang melakukan percobaan lintas tenant pada platform yang sama.

Kebijakan Fallback Pengiriman Cadangan (SMS)

Pada dasbor Komunikasi → Pengaturan Pengiriman, terdapat fitur Graceful Degradation yang memastikan tingkat keberhasilan verifikasi tetap konsisten meskipun layanan pesan instan Meta (WhatsApp) mengalami gangguan.

  • Deteksi Gangguan (Timeout & Bounce): Ketika API pengiriman Meta Cloud memberikan respons galat (HTTP 5xx) atau koneksi timeout (melebihi 5.000 milidetik), peladen secara otomatis menghentikan blokir aliran thread dan beralih ke saluran sekunder.
  • Rute Pengganti (SMS Provider Route): Sistem membangkitkan integrasi Zenziva atau penyedia SMS tepercaya lainnya untuk menyuntikkan payload pesan. Karena karakter pada SMS lebih terbatas, template yang dipakai akan direduksi untuk sekadar menampilkan nama jenama, kode 6 digit, dan peringatan durasi (contoh: DagangBot: Kode OTP Anda 849201. Jangan beri tahu siapa pun. Berlaku 5 menit.).
  • Proporsi Saldo (Credit Deductions): Meskipun proses fallback ini sepenuhnya nirkabel di level pengguna akhir, ia membawa dampak penagihan. Pengiriman rute WhatsApp dinilai jauh lebih ekonomis ketimbang SMS. Setiap keberhasilan fallback akan langsung mencatatkan transaksi pengeluaran (ledger deduction) sebesar nilai harga satuan pengiriman pesan singkat, yang langsung dipotong dari keseimbangan kredit akun merchant bersangkutan. Bila kredit menyentuh ambang nol, pengiriman SMS tidak dieksekusi.

Infrastruktur pengiriman pesan ini tidak hanya melayani verifikasi pendaftaran akun, melainkan juga dimanfaatkan secara lateral oleh layanan-layanan lain di dalam ekosistem platform.

  • Modul Autentikasi (/auth/register, /auth/verify-otp): Pada rute autentikasi publik, pendaftaran pengguna langsung memicu fungsi Send. Kegagalan verifikasi ditolak di lapisan handler dan tidak diizinkan mengeluarkan Token JWT.
  • Sistem Billing (Pembayaran Kredit): Biaya yang ditimbulkan saat mengirim OTP—terutama ketika melewati layanan SMS fallback dari Zenziva—akan mengurangi saldo kredit pada modul Billing. Logika ini melintas batas paket, merekam jumlah pesan (1 credit WA vs N credit SMS).
  • Modul Komunikasi (Notifikasi): Engine templat yang memproses penggantian sintaks {{key}} digunakan secara bersama (re-usable) oleh Notification Service untuk mengabarkan perubahan status keranjang belanja dan pembatalan draf invoice.

Kode yang merespons verifikasi akan menghitung kecocokan menggunakan HMAC-SHA256 di mana secret merupakan kombinasi antara serverSecret, identitas tenant, dan nomor pelanggan (subject). Karena hash tidak pernah bergerak melalui antarmuka publik, manipulasi permintaan (seperti mengubah payload HTTP) tidak akan menembus lapisan pelindung kriptografik ini.

6. Pemecahan Masalah (Troubleshooting)

Kendala pada sistem pengiriman pesan biasanya bersifat situasional—mulai dari ketersediaan sinyal telepon hingga batas harian. Analisis di bawah menguraikan akar masalah yang kerap terjadi beserta jalan keluarnya.

Simtom (Gejala) yang Dilaporkan Analisis Akar Penyebab Prosedur Solusi & Perbaikan
Pesan Error rate limit exceeded: max 10 verify attempts Pengguna mencoba memverifikasi OTP lebih dari 10 kali dalam satu menit, menyentuh batas ratelimit:otp:verify. Hentikan percobaan klien aplikasi. Minta pengguna menunggu setidaknya 60 detik sebelum melakukan validasi angka yang sama.
Respons 429: tenant daily limit reached Merchant kehabisan jatah total harian pengiriman OTP sebanyak 500 permintaan. Admin penyewa perlu masuk ke dasbor dan memutakhirkan langganan kuota batas harian atau menghubungi tim penyokong teknis.
Error otp delivery failed: no reachable channel Jaringan WhatsApp mengalami down dan merchant tidak mengaktifkan fitur SMS fallback, atau saldo kredit SMS habis. Aktifkan preferensi rute SMS cadangan pada pengaturan modul Komunikasi, dan periksa apakah nomor klien bebas dari penangguhan operator genggam.
Klien menerima reason: "invalid_code" terus-menerus padahal baru salah 1 kali Aplikasi klien memformat string nomor ponsel atau mengaburkan nol di awal yang berbeda dengan nomor saat Send. Pastikan parameter phone_number dinormalisasi (menghilangkan + awalan dan spasi) pada request payload POST /otp/verify secara persis identik dengan pemanggilan Send.
OTP tidak diverifikasi akibat reason: "expired" padahal baru diterima Pesan WA tertahan pada antrean server Meta selama 4 menit, sedangkan masa hidup OTP dikonfigurasi 5 menit. Pada saat periode trafik padat kampanye promosi, panjangkan durasi default_expiry_minutes (opsi 10 atau 15 menit) lewat Dasbor Pengaturan.

7. Referensi Terkait

Pelajari instrumen dan pengaturan terhubung lainnya yang merajut keamanan di dalam aplikasi dagang Anda.

content/docs/features/otp.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot