Dokumentasi Seller API

Autentikasi

Base URL: https://kodeotp.id/api/v1. Kirim API key pada header Authorization: Bearer ko_live_…. Key dibuat di Dashboard → Seller API dan hanya ditampilkan sekali. Akses Seller API terbuka permanen setelah satu top up berhasil minimal Rp100.000. Key nonaktif atau dicabut akan ditolak (401).

Batas request: 120 request/menit per key (429 RATE_LIMITED).

Idempotency

Endpoint pembelian wajib menyertakan header Idempotency-Key (8–120 karakter). Mengulang request dengan key dan body yang sama mengembalikan respons pertama tanpa membeli ulang (header Idempotent-Replayed: true). Key yang sama dengan body berbeda ditolak 422. Jika koneksi terputus, ulangi dengan key yang sama — jangan membuat key baru untuk transaksi yang sama.

Format error

{"success": false, "error": {"code": "INSUFFICIENT_BALANCE", "message": "Saldo tidak mencukupi."}}

Akun

GET /me — saldo, diskon OTP API, sisa slot aktif, batas per order.

OTP

• GET /otp/services — layanan tersedia + harga mulai (harga API).
• GET /otp/countries?service=wa — negara, country_id, harga API, stok.
• GET /otp/price?service=wa&country=1 — harga satu kombinasi.
• POST /otp/orders — body {"service":"wa","country":1,"quantity":1,"max_price":2500}. Harga API = harga retail − 10%.
• GET /otp/orders/{order_code} — status order dan setiap nomor.
• GET /otp/activations/{id} — status nomor + kode SMS (memicu pengecekan ke provider).
• POST /otp/activations/{id}/cancel — batalkan (setelah 2 menit); refund ke saldo per nomor setelah pembatalan dikonfirmasi provider (respons tidak pasti → status cancel_pending sampai terkonfirmasi).
• POST /otp/activations/{id}/finish — selesaikan nomor yang sudah menerima kode.

curl -X POST https://kodeotp.id/api/v1/otp/orders \
  -H "Authorization: Bearer ko_live_xxx" \
  -H "Idempotency-Key: order-20261102-0001" \
  -H "Content-Type: application/json" \
  -d '{"service":"wa","country":1,"quantity":1}'

Pulsa & paket

Produk pulsa, paket data, paket bicara, dan masa aktif memakai harga normal tanpa diskon.

• GET /iak/products?category=pulsa|data|bicara|masa_aktif&operator=telkomsel
• POST /iak/orders — body {"product_code":"…","customer_no":"0812…","max_price":11000} + Idempotency-Key.
• GET /iak/orders/{ref_id} — status transaksi.

Status

Nomor OTP: processing, waiting (menunggu SMS), received (kode masuk), cancel_pending, unknown (diverifikasi otomatis), completed, cancelled, expired, failed. Field refunded menunjukkan saldo sudah dikembalikan.

Pulsa & paket: processing, pending (menunggu provider — tidak direfund sampai status final), success, failed (direfund otomatis sekali).