Base URL https://dewaotp.top/api · Autentikasi: cookie otp_token (JWT httpOnly)
Dokumentasi API dewaotp.top (brand: DEWA OTP), toko nomor virtual / OTP.
Semua endpoint berada di bawah satu catch-all route Next.js sehingga setiap path diawali /api. Autentikasi memakai JWT di cookie httpOnly bernama otp_token; tidak ada Bearer token. Klien non-browser harus mengirim cookie tersebut sendiri.
Alur utama: 1. POST /auth/register atau POST /auth/login, cookie otp_token terpasang 2. POST /deposits membuat tagihan QRIS BoomPay beserta qrPayload untuk dirender menjadi QR 3. Pembeli membayar; status berubah PAID otomatis lewat webhook BoomPay (atau POST /deposits/{id}/check-status bila webhook belum terdaftar) 4. POST /orders membeli nomor; POST /orders/{id}/poll mengambil kode OTP
Catatan uang: saldo wallet disimpan dalam USD, tetapi semua angka yang dilihat pengguna ditampilkan dalam Rupiah memakai kurs efektif platform (GET /exchange-rate). Nominal yang ditagih QRIS = harga order + fee + kode unik dari gateway, sehingga bisa berbeda beberapa rupiah dari perhitungan fee internal (feeInfo.totalAmount hanya perkiraan).
Semua endpoint (47)
Detail endpoint
GET/
Health check
Grup: Publik · Autentikasi: Publik (tanpa login)
Respons
Kode
Arti
Skema
200
API hidup
object
GET/popular-services
Daftar layanan populer (statis)
Grup: Publik · Autentikasi: Publik (tanpa login)
Respons
Kode
Arti
Skema
200
Daftar layanan
object
GET/exchange-rate
Kurs USD ke IDR yang dipakai platform
Rate sudah termasuk spread platform; dipakai untuk menampilkan saldo dan harga dalam Rupiah.
Grup: Publik · Autentikasi: Publik (tanpa login)
Respons
Kode
Arti
Skema
200
Kurs aktif
ExchangeRate
GET/qris-fee-info
Konfigurasi biaya QRIS (untuk tampilan)
Grup: Publik · Autentikasi: Publik (tanpa login)
Respons
Kode
Arti
Skema
200
Konfigurasi biaya
QrisFeeInfo
POST/auth/register
Registrasi akun baru
Password minimal 8 karakter. Cookie sesi langsung dipasang bila berhasil.
Grup: Auth · Autentikasi: Publik (tanpa login)
Body permintaan
Field
Tipe
Keterangan
fullNamewajib
string
Budi Santoso
emailwajib
string · email
passwordwajib
string
Respons
Kode
Arti
Skema
200
Akun dibuat
object
400
Permintaan tidak valid
Error
POST/auth/login
Login
Mengembalikan Set-Cookie otp_token (httpOnly, sameSite=lax). remember=true memperpanjang sesi menjadi 30 hari, default 7 hari.
Grup: Auth · Autentikasi: Publik (tanpa login)
Body permintaan
Field
Tipe
Keterangan
emailwajib
string · email
passwordwajib
string
remember
boolean
Respons
Kode
Arti
Skema
200
Berhasil
object
401
Email atau password salah
Error
POST/auth/logout
Logout (hapus cookie sesi)
Grup: Auth · Autentikasi: Cookie otp_token
Respons
Kode
Arti
Skema
200
OK
object
GET/auth/me
Data pengguna yang sedang login
Grup: Auth · Autentikasi: Cookie otp_token
Respons
Kode
Arti
Skema
200
OK
object
401
Belum login
Error
POST/auth/forgot-password
Minta tautan reset password
Selalu menjawab sukses walau email tidak terdaftar, untuk mencegah enumerasi akun.
Grup: Auth · Autentikasi: Publik (tanpa login)
Body permintaan
Field
Tipe
Keterangan
emailwajib
string · email
Respons
Kode
Arti
Skema
200
Permintaan diterima
object
POST/auth/reset-password
Setel password baru dengan token reset
Grup: Auth · Autentikasi: Publik (tanpa login)
Body permintaan
Field
Tipe
Keterangan
tokenwajib
string
passwordwajib
string
Respons
Kode
Arti
Skema
200
Password diganti
object
400
Token tidak valid atau kedaluwarsa
Error
PATCH/profile
Ubah nama tampilan
Grup: Profil · Autentikasi: Cookie otp_token
Body permintaan
Field
Tipe
Keterangan
fullNamewajib
string
Respons
Kode
Arti
Skema
200
OK
object
401
Belum login
Error
POST/profile/password
Ganti password
Grup: Profil · Autentikasi: Cookie otp_token
Body permintaan
Field
Tipe
Keterangan
currentwajib
string
Password lama
nextwajib
string
Password baru
Respons
Kode
Arti
Skema
200
OK
object
400
Password lama salah atau password baru terlalu pendek
Error
GET/dashboard/summary
Ringkasan akun
Grup: Dashboard · Autentikasi: Cookie otp_token
Respons
Kode
Arti
Skema
200
OK
object
401
Belum login
Error
GET/numbers/countries
Daftar negara yang tersedia
Grup: Katalog Nomor · Autentikasi: Cookie otp_token
Respons
Kode
Arti
Skema
200
OK
object
401
Belum login
Error
GET/numbers/services
Daftar layanan untuk satu negara
Grup: Katalog Nomor · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
country
query
ya
string
Respons
Kode
Arti
Skema
200
OK
object
400
Parameter country wajib
Error
GET/numbers/prices
Harga per layanan (sudah termasuk markup platform)
Grup: Katalog Nomor · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
country
query
ya
string
Respons
Kode
Arti
Skema
200
OK
object
400
Parameter country wajib
Error
GET/numbers/balance
Saldo penyedia nomor (internal)
Grup: Katalog Nomor · Autentikasi: Cookie otp_token
Respons
Kode
Arti
Skema
200
OK
object
502
Provider tidak dapat dihubungi
Error
POST/orders
Beli nomor
Saldo wallet harus cukup (USD). Harga final dihitung server. Bila pembelian gagal, saldo dikembalikan otomatis.
Grup: Order · Autentikasi: Cookie otp_token
Body permintaan
Field
Tipe
Keterangan
service
string
wa
country
string
6
serviceName
string
WhatsApp
countryName
string
Indonesia
Respons
Kode
Arti
Skema
200
Nomor berhasil dibeli
object
400
Saldo kurang, layanan habis, atau provider menolak
Memanggil provider; bila OTP sudah masuk, order berubah menjadi RECEIVED.
Grup: Order · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
id
path
ya
string · uuid
Respons
Kode
Arti
Skema
200
OK
object
400
Order tidak bisa diproses
Error
POST/orders/{id}/cancel
Batalkan order
Membatalkan order di provider dan mengembalikan saldo bila memenuhi syarat.
Grup: Order · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
id
path
ya
string · uuid
Respons
Kode
Arti
Skema
200
OK
object
400
Order tidak bisa dibatalkan
Error
POST/deposits
Buat tagihan top-up QRIS
Minimal Rp 10.000. Server membuat charge ke BoomPay dan mengembalikan qrPayload (string QRIS EMVCo) untuk dirender menjadi QR di klien.
Nominal yang benar-benar ditagih adalah deposit.providerData.billedAmount (harga order + fee gateway + kode unik). feeInfo.totalAmount hanya perkiraan internal untuk tampilan, bukan angka tagihan.
Menanyakan status ke BoomPay dengan API key server sendiri (bukan mempercayai klien). Bila sudah dibayar, deposit menjadi PAID dan saldo dikreditkan tepat satu kali. Aman dipanggil berulang (idempoten).
Grup: Deposit · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
id
path
ya
string · uuid
Respons
Kode
Arti
Skema
200
Status terbaru
object
404
Deposit tidak ditemukan atau bukan milik pengguna ini
Error
500
Pengecekan gagal (gateway tidak merespons)
Error
POST/deposits/{id}/cancel
Batalkan deposit yang masih PENDING
BoomPay tidak punya endpoint cancel, jadi pembatalan ditandai di database.
Grup: Deposit · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
id
path
ya
string · uuid
Respons
Kode
Arti
Skema
200
OK
object
400
Status deposit bukan PENDING
Error
POST/deposits/{id}/confirm
[DEPRECATED] Konfirmasi manual
Endpoint ini sudah DEPRECATED.
Tidak lagi memproses apa pun. Konfirmasi hanya lewat webhook BoomPay atau check-status.
Callback dari BoomPay (didaftarkan di dashboard BoomPay)
Bukan untuk pengguna. URL terdaftar: https://dewaotp.top/api/boompay/webhook
Isi body tidak dipercaya. Handler mengambil merchant_order_id lalu memverifikasi ulang ke GET https://app.boompay.io/api/v1/pg/charge/{id} memakai API key server. Hanya jawaban API yang boleh mengkreditkan saldo. Idempoten: pengiriman ulang tidak menambah saldo lagi.
Grup: Webhook · Autentikasi: Publik (tanpa login)
Body permintaan
Field
Tipe
Keterangan
merchant_order_id
string
DEP-ab3f2c29-17e7-468f-83a5-0c030a7da0a3
Respons
Kode
Arti
Skema
200
Diterima; applied=false bila belum lunas atau sudah dikreditkan
object
500
Gagal diproses; pengirim akan mencoba ulang dan handler idempoten
—
GET/reseller/balance
Saldo wallet penjual
Nilai disimpan USD; ekuivalen Rupiah memakai kurs efektif platform.
Grup: API Penjual · Autentikasi: Cookie otp_token
Respons
Kode
Arti
Skema
200
OK
ResellerBalance
401
API key tidak ada / tidak valid
—
GET/reseller/countries
Daftar negara
Grup: API Penjual · Autentikasi: Cookie otp_token
Respons
Kode
Arti
Skema
200
OK
object
GET/reseller/services
Layanan + harga + stok untuk satu negara
Grup: API Penjual · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
country
query
ya
string
Respons
Kode
Arti
Skema
200
OK
object
400
country wajib
—
GET/reseller/prices
Harga per layanan
Grup: API Penjual · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
country
query
ya
string
Respons
Kode
Arti
Skema
200
OK
object
POST/reseller/orders
Beli nomor (memotong saldo)
Saldo wallet pemilik kunci dipotong sebesar price_usd; bila penyedia gagal, saldo tidak ditarik.
Batas harga modal per nomor (dari /reseller/tiers). Nomor dibeli pada paket harga ini atau lebih murah.
operator
string
Kode operator (opsional), lihat daftar operator di /reseller/tiers telkomsel
Respons
Kode
Arti
Skema
200
OK
object
400
Field kurang / SERVICE_NOT_AVAILABLE
—
402
INSUFFICIENT_BALANCE
—
429
RATE_LIMITED (lihat header retry-after)
—
GET/reseller/orders
Riwayat order milik kunci
Grup: API Penjual · Autentikasi: Cookie otp_token
Respons
Kode
Arti
Skema
200
OK
object
GET/reseller/orders/{id}
Detail satu order
Grup: API Penjual · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
id
path
ya
string · uuid
Respons
Kode
Arti
Skema
200
OK
object
404
Tidak ditemukan / bukan milik kunci ini
—
POST/reseller/orders/{id}/poll
Ambil OTP terbaru
Memanggil penyedia. Saat OTP pertama masuk, webhook dikirim ke URL kunci (3 percobaan, backoff 1s & 3s, header x-signature).
Grup: API Penjual · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
id
path
ya
string · uuid
Respons
Kode
Arti
Skema
200
OK
object
POST/reseller/orders/{id}/cancel
Batalkan order + refund
Saldo dikembalikan lewat ledger sebagai transaksi REFUND.
Grup: API Penjual · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
id
path
ya
string · uuid
Respons
Kode
Arti
Skema
200
OK
object
GET/reseller/offers
Pilihan harga lintas negara untuk satu layanan
Semua negara yang menyediakan layanan ini, diurutkan dari termurah ke termahal. `tier`: termurah | hemat | standar | premium (kuantil harga).
Grup: API Penjual · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
service
query
ya
string
limit
query
tidak
integer
Respons
Kode
Arti
Skema
200
OK
object
400
service wajib
—
502
PRICES_UNAVAILABLE
—
GET/reseller/tiers
Paket harga (tier) untuk satu layanan di satu negara
Daftar harga bertingkat dari penyedia: harga → jumlah nomor tersedia, diurutkan dari termurah. `provider_price_usd` dipakai sebagai `max_price` saat membeli.
Grup: API Penjual · Autentikasi: Cookie otp_token
Parameter
Nama
Lokasi
Wajib
Tipe
service
query
ya
string
country
query
ya
string
Respons
Kode
Arti
Skema
200
OK
object
400
service dan country wajib
—
502
TIERS_UNAVAILABLE
—
Skema data
Error
Field
Tipe
Keterangan
error
string
Unauthorized
ExchangeRate
Field
Tipe
Keterangan
base
string
USD
target
string
IDR
liveRate
number
18154.555202
spread
number
1.03
effectiveRate
number
Rate yang dipakai platform, termasuk spread 18699.19185806
oneUsdInIdr
number
18699.19185806
fetchedAt
integer
Epoch milidetik
QrisFeeInfo
Field
Tipe
Keterangan
enabled
boolean
percent
number
0.7
lowFixed
integer
310
highPercent
number
highFixed
integer
threshold
integer
105000
feePaidByUser
boolean
User
Field
Tipe
Keterangan
id
string · uuid
fullName
string
email
string · email
balance
number
Saldo dalam USD; UI menampilkannya sebagai Rupiah 0.5348