REST API v1

Dokumentasi API MangoOTP untuk pengembang

Otomatiskan penerimaan SMS satu kali melalui Partner API. Permintaan wajib memakai X-API-Key dan mematuhi daftar IP, nomor pesanan mitra, batas laju, serta frekuensi polling.

codeLihat panduan API keyBuat kunci API

Alur mulai cepat

Integrasi umum terdiri dari empat langkah, dari kredensial hingga SMS diterima.

Buat kunci API

Setelah masuk, buat kunci berawalan mago_live_ dari halaman Kunci API. Kunci asli hanya ditampilkan satu kali.

Setiap akun hanya menyimpan satu kunci mitra aktif. Atur daftar IP keluar tetap dan URL Webhook sebelum digunakan di lingkungan produksi.

Ambil harga layanan-negara

Ambil daftar layanan, ambil negara yang tersedia untuk layanan tersebut, lalu minta satu harga platform dan perkiraan stok untuk pasangan layanan-negara.

Respons hanya memuat harga platform dan data stok yang dibutuhkan aplikasi.

Buat pesanan OTP

Kirim service, country, sellPrice, dan maxSellPrice opsional bersama partnerOrderNo agar saldo tidak dibekukan dua kali saat dicoba ulang.

Tanpa maxSellPrice harga saat ini harus sama dengan sellPrice; bila batas dikirim, harga saat ini tidak boleh melampauinya.

Polling status pesanan

Cari berdasarkan nomor pesanan untuk memperoleh nomor telepon, kode SMS, dan status siklus hidup.

Coba lagi hanya setelah ada kegagalan pasti, stok habis, atau harga ditolak.

shield

Autentikasi

Semua permintaan API Mitra memakai X-API-Key. Sistem hanya menyimpan hash SHA-256 dan IP koneksi harus cocok dengan daftar izin yang tidak kosong. X-Forwarded-For tidak dipercaya untuk keputusan ini.

X-API-Key: mago_live_xxxxxxxxxxxxxxxx

bolt

Nomor pesanan mitra dan perlindungan harga

POST /api/v1/activation/createOrder memakai partnerOrderNo, sellPrice wajib, dan maxSellPrice opsional. Percobaan ulang yang sama tidak membuat pesanan duplikat; harga serta kelayakan jual saat ini diperiksa sebelum dana dibekukan.

{"partnerOrderNo":"partner-order-20260707-001"}

Panduan endpoint

Dokumentasi per endpoint mengikuti urutan integrasi umum: URL, parameter, contoh permintaan, respons berhasil, dan kesalahan umum.

API Mitra

API penerimaan OTP dan baca saldo MAIN dengan autentikasi X-API-Key independen. Pengelolaan kunci API tetap berada di area User yang sudah masuk.

GET/api/v1/activation/getServices

Ambil daftar layanan

X-API-Key

Mengembalikan layanan OTP aktif untuk pemilih layanan dan penyegaran cache katalog mitra secara berkala.

Parameter	Lokasi	Tipe	Wajib	Deskripsi
X-API-Key	Header	string	ya	Kunci API mitra. IP pemanggil harus cocok dengan daftar IP yang diizinkan untuk kunci tersebut.
X-Request-Id	Header	string	tidak	ID korelasi mitra opsional berisi 1-64 huruf, angka, titik, garis bawah, titik dua, atau tanda hubung; dicatat dalam audit tetapi tidak menggantikan X-Trace-Id.

Kolom respons	Tipe	Wajib	Deskripsi
code	string	ya	Kode bisnis dan satu-satunya dasar keputusan bisnis yang dapat dibaca mesin. Keberhasilan selalu 0; kesalahan mengikuti katalog kode kesalahan.
message	string	ya	Hanya teks bantu untuk log; jangan mengurai atau menjadikannya dasar keputusan bisnis. Backend hanya memelihara bahasa Inggris dan Tionghoa Sederhana; permintaan bahasa Indonesia menerima message bahasa Inggris.
data	array	ya	Payload bisnis. Biasanya null ketika code bukan 0.
data[]	array	ya	Daftar layanan dalam urutan tampilan platform.
data[].serviceCode	string	ya	Kode layanan platform untuk negara, penawaran, dan pesanan.
data[].serviceName	string	ya	Nama tampilan layanan.

Contoh permintaan

GET https://api.mangootp.com/api/v1/activation/getServices
X-API-Key: mago_live_xxx
Accept: application/json

Respons berhasil

{
  "code": "0",
  "message": "success",
  "data": [
    {
      "serviceCode": "telegram",
      "serviceName": "Telegram"
    }
  ]
}

Kesalahan umum

AUTH-E001: kunci API tidak ada.
AUTH-E002: kunci API tidak valid, dicabut, kedaluwarsa, atau IP tidak cocok.

GET/api/v1/activation/getCountries

Ambil negara yang didukung

X-API-Key

Mengembalikan semua negara aktif yang didukung sistem tanpa parameter bisnis.

Parameter	Lokasi	Tipe	Wajib	Deskripsi
X-API-Key	Header	string	ya	Kunci API mitra. IP pemanggil harus cocok dengan daftar IP yang diizinkan untuk kunci tersebut.
X-Request-Id	Header	string	tidak	ID korelasi mitra opsional berisi 1-64 huruf, angka, titik, garis bawah, titik dua, atau tanda hubung; dicatat dalam audit tetapi tidak menggantikan X-Trace-Id.

Kolom respons	Tipe	Wajib	Deskripsi
code	string	ya	Kode bisnis dan satu-satunya dasar keputusan bisnis yang dapat dibaca mesin. Keberhasilan selalu 0; kesalahan mengikuti katalog kode kesalahan.
message	string	ya	Hanya teks bantu untuk log; jangan mengurai atau menjadikannya dasar keputusan bisnis. Backend hanya memelihara bahasa Inggris dan Tionghoa Sederhana; permintaan bahasa Indonesia menerima message bahasa Inggris.
data	array	ya	Payload bisnis. Biasanya null ketika code bukan 0.
data[]	array	ya	Semua negara aktif yang didukung sistem.
data[].countryCode	string	ya	Kode negara ISO untuk penawaran dan pesanan.
data[].countryName	string	ya	Nama negara untuk lokal saat ini.
data[].flagEmoji	string / null	tidak	Emoji bendera negara.
data[].phonePrefix	string / null	tidak	Kode panggilan negara.

Contoh permintaan

GET https://api.mangootp.com/api/v1/activation/getCountries
X-API-Key: mago_live_xxx
Accept: application/json

Respons berhasil

{
  "code": "0",
  "message": "success",
  "data": [
    {
      "countryCode": "US",
      "countryName": "United States",
      "flagEmoji": "🇺🇸",
      "phonePrefix": "+1"
    }
  ]
}

Kesalahan umum

AUTH-E001: kunci API tidak ada.
AUTH-E002: kunci API tidak valid, dicabut, kedaluwarsa, atau IP tidak cocok.

GET/api/v1/activation/getPrice

Ambil harga layanan-negara

X-API-Key

Mengembalikan harga jual platform dan perkiraan stok saat ini tanpa menerbitkan token penawaran.

Parameter	Lokasi	Tipe	Wajib	Deskripsi
X-API-Key	Header	string	ya	Kunci API mitra. IP pemanggil harus cocok dengan daftar IP yang diizinkan untuk kunci tersebut.
X-Request-Id	Header	string	tidak	ID korelasi mitra opsional berisi 1-64 huruf, angka, titik, garis bawah, titik dua, atau tanda hubung; dicatat dalam audit tetapi tidak menggantikan X-Trace-Id.
service	Query	string	ya	Kode layanan platform.
country	Query	string	ya	Kode negara ISO, misalnya US atau GB.

Kolom respons	Tipe	Wajib	Deskripsi
code	string	ya	Kode bisnis dan satu-satunya dasar keputusan bisnis yang dapat dibaca mesin. Keberhasilan selalu 0; kesalahan mengikuti katalog kode kesalahan.
message	string	ya	Hanya teks bantu untuk log; jangan mengurai atau menjadikannya dasar keputusan bisnis. Backend hanya memelihara bahasa Inggris dan Tionghoa Sederhana; permintaan bahasa Indonesia menerima message bahasa Inggris.
data	object	ya	Payload bisnis. Biasanya null ketika code bukan 0.
data.service	string	ya	Kode layanan yang diminta.
data.country	string	ya	Kode negara yang diminta.
data.sellPrice	decimal number	ya	Harga jual unit dari baris Catalog saat ini.
data.currency	string	ya	Kode mata uang harga yang saat ini dikembalikan API adalah USD.
data.availableCount	integer	ya	Perkiraan stok Catalog saat ini; jumlah ini bukan reservasi bagi pemanggil.

Contoh permintaan

GET https://api.mangootp.com/api/v1/activation/getPrice?service=telegram&country=US
X-API-Key: mago_live_xxx
Accept: application/json

Respons berhasil

{
  "code": "0",
  "message": "success",
  "data": {
    "service": "telegram",
    "country": "US",
    "sellPrice": 1.050000,
    "currency": "USD",
    "availableCount": 42
  }
}

Kesalahan umum

OTP-E006: stok tidak tersedia untuk pasangan layanan-negara ini.
COMMON-E002: format service atau country tidak valid.
AUTH-E002: kunci API ditolak.

POST/api/v1/activation/createOrder

Buat pesanan OTP

X-API-Key

Membuat pesanan OTP dan membekukan harga Catalog saat ini; partnerOrderNo menjamin idempotensi dan maxSellPrice opsional membatasi perubahan harga.

Parameter	Lokasi	Tipe	Wajib	Deskripsi
X-API-Key	Header	string	ya	Kunci API mitra. IP pemanggil harus cocok dengan daftar IP yang diizinkan untuk kunci tersebut.
X-Request-Id	Header	string	tidak	ID korelasi mitra opsional berisi 1-64 huruf, angka, titik, garis bawah, titik dua, atau tanda hubung; dicatat dalam audit tetapi tidak menggantikan X-Trace-Id.
partnerOrderNo	Body	string	ya	Nomor pesanan yang dibuat sistem mitra. Nomor harus unik pada akun mitra dan bisnis OTP yang sama, serta tetap sama ketika permintaan yang sama dicoba ulang.
service	Body	string	ya	Kode layanan platform.
country	Body	string	ya	Kode negara ISO.
sellPrice	Body	decimal number	ya	Harga jual platform yang terakhir dibaca mitra; harus positif dengan maksimal enam angka desimal.
maxSellPrice	Body	decimal number	tidak	Batas harga opsional yang tidak boleh lebih kecil dari sellPrice. Jika dihilangkan, perubahan harga tidak diterima.

Kolom respons	Tipe	Wajib	Deskripsi
code	string	ya	Kode bisnis dan satu-satunya dasar keputusan bisnis yang dapat dibaca mesin. Keberhasilan selalu 0; kesalahan mengikuti katalog kode kesalahan.
message	string	ya	Hanya teks bantu untuk log; jangan mengurai atau menjadikannya dasar keputusan bisnis. Backend hanya memelihara bahasa Inggris dan Tionghoa Sederhana; permintaan bahasa Indonesia menerima message bahasa Inggris.
data	object	ya	Payload bisnis. Biasanya null ketika code bukan 0.
data.orderNo	string	ya	Nomor pesanan OTP MangoOTP.
data.partnerOrderNo	string	ya	Nomor pesanan mitra.
data.status	string	ya	Status pesanan OTP saat ini.
data.phone	string / null	tidak	Nomor telepon yang dialokasikan; null sebelum alokasi.
data.smsCode	string / null	tidak	OTP yang diekstrak; null sebelum SMS diterima.
data.payAmount	decimal number	ya	Jumlah yang harus dibayar pengguna, dibekukan dan diselesaikan untuk pesanan.
data.currency	string	ya	Mata uang pesanan, saat ini selalu USD.

Contoh permintaan

POST https://api.mangootp.com/api/v1/activation/createOrder
X-API-Key: mago_live_xxx
Accept: application/json
Content-Type: application/json

{
  "partnerOrderNo": "partner-order-20260707-001",
  "service": "telegram",
  "country": "US",
  "sellPrice": 1.05,
  "maxSellPrice": 1.10
}

Respons berhasil

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "PENDING",
    "phone": null,
    "smsCode": null,
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

Kesalahan umum

ACC-E004: saldo tersedia tidak mencukupi.
ORD-E004: token penawaran atau batas harga yang diterima tidak valid.
OTP-E006: Catalog saat ini tidak memiliki stok.
COMMON-E003: format atau presisi batas harga tidak valid.

GET/api/v1/activation/getOrders

Ambil daftar pesanan OTP

X-API-Key

Membagi halaman pesanan OTP milik pengguna pemilik kunci API untuk sinkronisasi riwayat dan rekonsiliasi status di sisi mitra.

Parameter	Lokasi	Tipe	Wajib	Deskripsi
X-API-Key	Header	string	ya	Kunci API mitra. IP pemanggil harus cocok dengan daftar IP yang diizinkan untuk kunci tersebut.
X-Request-Id	Header	string	tidak	ID korelasi mitra opsional berisi 1-64 huruf, angka, titik, garis bawah, titik dua, atau tanda hubung; dicatat dalam audit tetapi tidak menggantikan X-Trace-Id.
page	Query	number	tidak	Nomor halaman; default 1.
size	Query	number	tidak	Ukuran halaman; default 20 dan dibatasi oleh platform.

Kolom respons	Tipe	Wajib	Deskripsi
code	string	ya	Kode bisnis dan satu-satunya dasar keputusan bisnis yang dapat dibaca mesin. Keberhasilan selalu 0; kesalahan mengikuti katalog kode kesalahan.
message	string	ya	Hanya teks bantu untuk log; jangan mengurai atau menjadikannya dasar keputusan bisnis. Backend hanya memelihara bahasa Inggris dan Tionghoa Sederhana; permintaan bahasa Indonesia menerima message bahasa Inggris.
data	object	ya	Payload bisnis. Biasanya null ketika code bukan 0.
data.total	number	ya	Jumlah total pesanan yang cocok.
data.records[]	array	ya	Daftar pesanan pada halaman saat ini.
data.records[].orderNo	string	ya	Nomor pesanan OTP MangoOTP.
data.records[].partnerOrderNo	string	ya	Nomor pesanan mitra.
data.records[].status	string	ya	Status pesanan OTP saat ini.
data.records[].serviceCode	string	ya	Kode layanan.
data.records[].countryCode	string	ya	Kode negara ISO.
data.records[].phone	string / null	tidak	Nomor telepon yang dialokasikan; null sebelum alokasi.
data.records[].smsCode	string / null	tidak	OTP yang diekstrak; null sebelum SMS diterima.
data.records[].payAmount	decimal number	ya	Jumlah yang harus dibayar pengguna, dibekukan dan diselesaikan untuk pesanan.
data.records[].refundAmount	decimal number	ya	Jumlah yang sudah dikembalikan kepada pengguna.
data.records[].createdAt	datetime string	ya	Waktu pembuatan pesanan.
data.records[].completedAt	datetime string / null	tidak	Waktu penyelesaian atau null sebelum selesai.

Contoh permintaan

GET https://api.mangootp.com/api/v1/activation/getOrders?page=1&size=20
X-API-Key: mago_live_xxx
Accept: application/json

Respons berhasil

{
  "code": "0",
  "message": "success",
  "data": {
    "total": 1,
    "records": [
      {
        "orderNo": "AO202607070000000001",
        "partnerOrderNo": "partner-order-20260707-001",
        "status": "ACTIVE",
        "serviceCode": "telegram",
        "countryCode": "US",
        "phone": "+12025550123",
        "smsCode": null,
        "payAmount": 1.050000,
        "refundAmount": 0.000000,
        "createdAt": "2026-06-22T18:07:22",
        "completedAt": null
      }
    ]
  }
}

Kesalahan umum

AUTH-E002: kunci API ditolak.
COMMON-E003: page atau size di luar rentang.

GET/api/v1/activation/getOrder?orderNo={orderNo}

Ambil detail pesanan OTP

X-API-Key

Membaca status, nomor telepon, dan kode SMS suatu pesanan. Periksa kode bisnis dan data.status, bukan hanya status HTTP.

Parameter	Lokasi	Tipe	Wajib	Deskripsi
X-API-Key	Header	string	ya	Kunci API mitra. IP pemanggil harus cocok dengan daftar IP yang diizinkan untuk kunci tersebut.
X-Request-Id	Header	string	tidak	ID korelasi mitra opsional berisi 1-64 huruf, angka, titik, garis bawah, titik dua, atau tanda hubung; dicatat dalam audit tetapi tidak menggantikan X-Trace-Id.
orderNo	Query	string	ya	Nomor pesanan OTP MangoOTP.

Kolom respons	Tipe	Wajib	Deskripsi
code	string	ya	Kode bisnis dan satu-satunya dasar keputusan bisnis yang dapat dibaca mesin. Keberhasilan selalu 0; kesalahan mengikuti katalog kode kesalahan.
message	string	ya	Hanya teks bantu untuk log; jangan mengurai atau menjadikannya dasar keputusan bisnis. Backend hanya memelihara bahasa Inggris dan Tionghoa Sederhana; permintaan bahasa Indonesia menerima message bahasa Inggris.
data	object	ya	Payload bisnis. Biasanya null ketika code bukan 0.
data.orderNo	string	ya	Nomor pesanan OTP MangoOTP.
data.partnerOrderNo	string	ya	Nomor pesanan mitra.
data.status	string	ya	Status pesanan OTP saat ini.
data.phone	string / null	tidak	Nomor telepon yang dialokasikan; null sebelum alokasi.
data.smsCode	string / null	tidak	OTP yang diekstrak; null sebelum SMS diterima.
data.payAmount	decimal number	ya	Jumlah yang harus dibayar pengguna, dibekukan dan diselesaikan untuk pesanan.
data.currency	string	ya	Mata uang pesanan, saat ini selalu USD.

Contoh permintaan

GET https://api.mangootp.com/api/v1/activation/getOrder?orderNo=AO202607070000000001
X-API-Key: mago_live_xxx
Accept: application/json

Respons berhasil

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "SUCCESS",
    "phone": "+12025550123",
    "smsCode": "834921",
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

Kesalahan umum

ORD-E001: pesanan tidak ada atau bukan milik pengguna pemilik kunci API.
COMMON-E002: format orderNo tidak valid.

POST/api/v1/activation/cancelOrder?orderNo={orderNo}

Batalkan pesanan OTP

X-API-Key

Membatalkan pesanan selama masih dapat dibatalkan. Pesanan yang sedang diproses, sudah menerima SMS, atau sudah berstatus akhir tidak dibatalkan lagi.

Parameter	Lokasi	Tipe	Wajib	Deskripsi
X-API-Key	Header	string	ya	Kunci API mitra. IP pemanggil harus cocok dengan daftar IP yang diizinkan untuk kunci tersebut.
X-Request-Id	Header	string	tidak	ID korelasi mitra opsional berisi 1-64 huruf, angka, titik, garis bawah, titik dua, atau tanda hubung; dicatat dalam audit tetapi tidak menggantikan X-Trace-Id.
orderNo	Query	string	ya	Nomor pesanan OTP MangoOTP.

Kolom respons	Tipe	Wajib	Deskripsi
code	string	ya	Kode bisnis dan satu-satunya dasar keputusan bisnis yang dapat dibaca mesin. Keberhasilan selalu 0; kesalahan mengikuti katalog kode kesalahan.
message	string	ya	Hanya teks bantu untuk log; jangan mengurai atau menjadikannya dasar keputusan bisnis. Backend hanya memelihara bahasa Inggris dan Tionghoa Sederhana; permintaan bahasa Indonesia menerima message bahasa Inggris.
data	object	ya	Payload bisnis. Biasanya null ketika code bukan 0.
data.orderNo	string	ya	Nomor pesanan OTP MangoOTP.
data.partnerOrderNo	string	ya	Nomor pesanan mitra.
data.status	string	ya	Status pesanan OTP saat ini.
data.phone	string / null	tidak	Nomor telepon yang dialokasikan; null sebelum alokasi.
data.smsCode	string / null	tidak	OTP yang diekstrak; null sebelum SMS diterima.
data.payAmount	decimal number	ya	Jumlah yang harus dibayar pengguna, dibekukan dan diselesaikan untuk pesanan.
data.currency	string	ya	Mata uang pesanan, saat ini selalu USD.

Contoh permintaan

POST https://api.mangootp.com/api/v1/activation/cancelOrder?orderNo=AO202607070000000001
X-API-Key: mago_live_xxx
Accept: application/json

Respons berhasil

{
  "code": "0",
  "message": "success",
  "data": {
    "orderNo": "AO202607070000000001",
    "partnerOrderNo": "partner-order-20260707-001",
    "status": "CANCELLED",
    "phone": null,
    "smsCode": null,
    "payAmount": 1.050000,
    "currency": "USD"
  }
}

Kesalahan umum

ORD-E003 / ORD-E005: status saat ini tidak mengizinkan pembatalan.
ORD-E001: pesanan tidak ada atau bukan milik pengguna pemilik kunci API.

GET/api/v1/account/getBalance

Ambil saldo akun

X-API-Key

Mengembalikan saldo MAIN pemilik hanya berdasarkan kunci API, tanpa menerima email atau ID pengguna.

Parameter	Lokasi	Tipe	Wajib	Deskripsi
X-API-Key	Header	string	ya	Kunci API mitra. IP pemanggil harus cocok dengan daftar IP yang diizinkan untuk kunci tersebut.
X-Request-Id	Header	string	tidak	ID korelasi mitra opsional berisi 1-64 huruf, angka, titik, garis bawah, titik dua, atau tanda hubung; dicatat dalam audit tetapi tidak menggantikan X-Trace-Id.

Kolom respons	Tipe	Wajib	Deskripsi
code	string	ya	Kode bisnis dan satu-satunya dasar keputusan bisnis yang dapat dibaca mesin. Keberhasilan selalu 0; kesalahan mengikuti katalog kode kesalahan.
message	string	ya	Hanya teks bantu untuk log; jangan mengurai atau menjadikannya dasar keputusan bisnis. Backend hanya memelihara bahasa Inggris dan Tionghoa Sederhana; permintaan bahasa Indonesia menerima message bahasa Inggris.
data	object	ya	Payload bisnis. Biasanya null ketika code bukan 0.
data.accountType	string	ya	Selalu MAIN.
data.currency	string	ya	Mata uang akun utama, saat ini USD.
data.availableBalance	decimal number	ya	Saldo tersedia akun utama saat ini.

Contoh permintaan

GET https://api.mangootp.com/api/v1/account/getBalance
X-API-Key: mago_live_xxx
Accept: application/json

Respons berhasil

{
  "code": "0",
  "message": "success",
  "data": {
    "accountType": "MAIN",
    "currency": "USD",
    "availableBalance": 97.410000
  }
}

Kesalahan umum

AUTH-E002: kunci API tidak valid, dicabut, kedaluwarsa, atau IP tidak cocok.
ACC-E001: akun MAIN tidak ditemukan.

Peristiwa Webhook

Webhook hanya memberi tahu saat pesanan aktivasi menerima SMS. Atur URL panggilan balik di halaman Kunci API.

activation.sms_received

SMS pesanan OTP diterima

Dikirim setelah MangoOTP menerima SMS dan mengekstrak OTP. Respons pembuatan pesanan sudah mengembalikan nomor telepon sehingga alokasi nomor OTP tidak dikirim sebagai Webhook terpisah.

{
  "eventId": "evt_AO202607070000000001_activation_sms_received",
  "eventType": "activation.sms_received",
  "status": "SUCCESS",
  "orderNo": "AO202607070000000001",
  "occurredAt": "2026-06-22T18:09:01Z",
  "data": {
    "orderNo": "AO202607070000000001",
    "service": "telegram",
    "country": "US",
    "phone": "+12025550123",
    "payAmount": 1.050000,
    "smsCode": "834921",
    "smsText": "Telegram code: 834921"
  }
}

verified_user

Tanda tangan Webhook dan percobaan ulang

Konfigurasi: pengguna yang sudah masuk mengatur satu URL Webhook untuk kunci API aktif dari halaman Kunci API. Webhook dan permintaan API dimiliki oleh pengguna yang sama.
Tanda tangan: setiap pengiriman menyertakan X-Webhook-Signature: sha256=<hex>. Hash API Key aktif dengan SHA-256 menjadi teks heksadesimal huruf kecil 64 karakter, lalu gunakan byte UTF-8 teks tersebut sebagai kunci HMAC-SHA256 untuk menandatangani byte isi HTTP JSON mentah secara langsung. Webhook tidak membuat rahasia penandatanganan terpisah.
Header: X-Webhook-Event memuat jenis peristiwa, X-Webhook-Delivery-Id tetap sama untuk semua notifikasi satu peristiwa, X-Webhook-Attempt memuat nomor notifikasi, dan X-Webhook-Timestamp memuat Unix timestamp dalam detik. Header tambahan ini tidak ikut ditandatangani.
Kebijakan notifikasi: maksimal 5 kali. Notifikasi pertama segera; jika belum diakui, notifikasi berikutnya dikirim setelah 1, 3, 5, dan 15 menit, yaitu pada menit relatif 0, 1, 4, 9, dan 24. Setelah notifikasi kelima hasil menjadi FAIL dan notifikasi manual tidak melewati batas.
Konfirmasi penerima: notifikasi berhenti hanya jika status HTTP 2xx dan isi respons setelah trim tepat SUCCESS. Verifikasi tanda tangan dan simpan secara idempoten berdasarkan eventId. Webhook tidak menggantikan API kueri pesanan.

Kolom Webhook	Tipe	Wajib	Deskripsi
eventType	string	ya	Jenis peristiwa bisnis, sama dengan X-Webhook-Event, misalnya activation.sms_received.
eventId	string	ya	ID peristiwa unik. Penerima harus menyimpan secara idempoten berdasarkan kolom ini.
status	string	tidak	Status pesanan setelah peristiwa. Tersedia untuk peristiwa pesanan.
orderNo	string	tidak	Nomor pesanan bisnis tingkat atas untuk peristiwa pesanan, berguna untuk perutean log dan peringatan.
occurredAt	datetime string	ya	Waktu peristiwa dalam format ISO-8601.
data.orderNo	string	ya	Nomor pesanan OTP MangoOTP dengan awalan AO.
data.service	string	tidak	Kode layanan. Kolom ini mungkin tidak ada pada peristiwa gagal.
data.country	string	tidak	Kode negara. Kolom ini mungkin tidak ada pada peristiwa gagal.
data.phone	string	tidak	Nomor telepon yang dialokasikan untuk pesanan OTP. Respons pembuatan pesanan sudah mengembalikannya dan Webhook SMS menyertakannya kembali.
data.smsCode	string	tidak	OTP yang diekstrak dari peristiwa penerimaan SMS.
data.smsText	string	tidak	Isi atau pratinjau SMS untuk tampilan maupun pemecahan masalah.
data.payAmount	decimal number	tidak	Jumlah yang dibayar pengguna pada peristiwa penerimaan SMS pesanan OTP.

Siklus hidup dan polling

Jangan hanya mengandalkan status HTTP. Baca kode bisnis dan status pesanan; status akhir tidak dapat dibatalkan.

PENDING

Pesanan telah dibuat dan sedang diproses atau menunggu hasil pasti. Status ini tidak dapat dibatalkan.

ACTIVE

Nomor telepon telah dialokasikan dan menunggu SMS. Polling detail pesanan untuk memperoleh smsCode.

SUCCESS

OTP telah diterima dan pesanan selesai. Ini adalah status akhir.

TIMEOUT / FAILED / CANCELLED / BANNED

Status akhir yang telah dikembalikan dananya atau dihentikan; arti khusus dibedakan oleh nama status.

Penanganan kesalahan

Kegagalan bisnis mengembalikan kode terpadu. Klien harus menentukan percobaan ulang, pergantian negara, isi saldo, atau penanganan manual berdasarkan kode.

Kode kesalahan	Arti	Tindakan yang disarankan
COMMON-E001 / E002 / E003	Parameter tidak ada, tidak valid, atau di luar rentang.	Periksa kolom wajib, panjang, presisi jumlah uang, dan format code.
AUTH-E001 / AUTH-E002	Autentikasi tidak ada atau tidak valid.	Periksa X-API-Key, status pencabutan, masa berlaku, dan daftar IP yang diizinkan.
ACC-E004	Saldo tersedia tidak mencukupi.	Isi saldo, pastikan saldo tersedia telah diperbarui, lalu coba lagi.
OTP-E006 / SMS-E003	Tidak ada stok untuk pilihan ini.	Coba negara/layanan lain atau ulangi nanti.
ORD-E001 / ORD-E003 / ORD-E005	Pesanan tidak ditemukan atau status saat ini tidak mengizinkan operasi.	Muat ulang status pesanan sebelum menentukan langkah berikutnya.
ORD-E004	sellPrice atau batas harga yang diterima tidak valid.	Ambil harga baru dan kirim sellPrice; kirim maxSellPrice hanya bila perubahan harga dapat diterima.
SMS-E001 / SMS-E004	Layanan nomor sementara tidak tersedia.	Periksa hasil berdasarkan nomor pesanan bisnis terlebih dahulu. Coba lagi hanya setelah kegagalan pasti; hubungi dukungan jika hasil tetap belum diketahui.

speed

Batas laju dan frekuensi polling

Batas laju kunci API: rateLimitQps dapat dikonfigurasi saat kunci dibuat. Nilai default adalah 5 QPS; batas maksimum saat ini ditampilkan pada halaman pembuatan kunci API di portal USER.
Batas jendela platform: jika tidak ada aturan khusus, GET default 300 permintaan/menit dan non-GET default 30 permintaan/menit. Pelanggaran batas mengembalikan HTTP 429 dan COMMON-E429.
Header HTTP: respons yang dibatasi menyertakan X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Klien harus memperpanjang jeda sebelum mencoba lagi berdasarkan header tersebut.
Kueri harga mengembalikan harga Catalog dan perkiraan stok saat ini tanpa masa berlaku; pembuatan pesanan selalu membaca ulang harga dan kelayakan jual.
Polling pesanan OTP: polling pesanan yang sama setiap 5-10 detik. Polling lebih cepat saat ACTIVE tidak mempercepat SMS dan meningkatkan risiko pembatasan.