Dokumentasi API Reseller

API reseller SHOP2TOPUP adalah JSON REST API untuk menjual top up game, isi ulang game, dan kode voucher dari toko, storefront, atau bot milikmu sendiri. Referensi ini mendokumentasikan setiap endpoint publik beserta parameter dan response-nya.

Base URL dan protokol

Semua path di referensi ini relatif terhadap base URL di bawah. Request dan response berupa JSON lewat HTTPS. Nominal dikirim sebagai string supaya tidak ada pembulatan float yang ikut masuk, dan semua timestamp memakai UTC dalam format ISO 8601.

https://shop2topup.com/api/endpoints/v1

Autentikasi

Tiap request cukup membawa satu header. Pasangan key dibuat dari halaman API Access di panel reseller kamu dan bisa dibatasi dengan IP allowlist. Panggilan dari alamat lain langsung ditolak dengan IP_NOT_ALLOWED sebelum sampai ke logika bisnis apa pun.

Header request

Authorization: Bearer <keyId>.<secret>

Panggilan pertama

Tidak perlu instal apa pun. Ganti dengan key milikmu, lalu panggilan ini mengembalikan data katalog live.

Permintaan - cURL

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Konvensi response

Semua response punya field boolean success, jadi satu percabangan sudah cukup untuk memisahkan alur sukses dari semua kegagalan.
Kalau gagal, response berisi objek error dengan kode yang stabil, pesan yang mudah dibaca, dan details opsional. Tentukan alur berdasarkan kode, jangan berdasarkan pesannya.
Uang selalu berupa string desimal seperti "0.950000" dalam USD. Jangan ubah ke binary float sebelum membandingkan atau menjumlahkannya.
Endpoint daftar mengembalikan objek pagination berisi page, limit, total, dan total_pages.
Pembuatan pesanan bersifat idempoten berdasarkan UUID order_id yang kamu kirim, jadi retry tidak akan pernah menagih dua kali.

Respons error

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "action": "FIX_INPUT",
    "retryable": false,
    "retry_after": null,
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

Bagian referensi

KatalogKatalog berbentuk pohon tiga level: big category berisi kategori, kategori berisi subkategori, dan subkategori adalah item yang benar-benar kamu beli. Lewat endpoint ini kamu bisa menyalin pohon itu ke database sendiri dan mengecek harga item tepat sebelum memesannya.Validasi pemainValidasi pemain mengecek akun in-game sebelum ada uang yang berpindah. Endpoint ini memastikan identifier tersebut ada untuk produk itu, mengembalikan nama in-game supaya pembeli bisa mengeceknya, dan menampilkan region-nya sehingga pesanan lintas region ditolak lebih awal, bukan gagal setelah pembayaran.PesananSetiap pesanan dibuat dengan UUID yang kamu generate sendiri. UUID itu jadi idempotency key: kalau dikirim ulang, kamu menerima pesanan aslinya dan tidak ditagih dua kali. Setelah itu, status bisa dibaca per pesanan, per batch berisi maksimal 50 pesanan, atau sebagai daftar dengan paginasi.Akun & autentikasiSemua request cukup membawa satu header. Panggil GET /account untuk memastikan API key kamu berfungsi, melihat saldo dompet yang dipakai untuk membayar pesanan, dan mengecek akun masih aktif sebelum menjalankan batch.Kode errorRequest yang gagal selalu mengembalikan kode stabil yang bisa dibaca mesin, bersama status HTTP-nya. Jadikan kode sebagai acuan logika, jangan teks pesannya: pesan ditulis untuk manusia dan kata-katanya bisa diubah, sedangkan kode adalah bagian dari kontrak.

Batas request

Limit berlaku per akun dengan rolling window. Endpoint katalog, pesanan, dan akun menyertakan X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset, sedangkan request yang kena throttle dibalas 429 dengan header Retry-After. Validasi pemain dihitung dari kuota cek pemain harianmu: tidak mengirim header X-RateLimit dan menampilkan kuotanya di body respons 429.

Rute	Jumlah request	Rentang waktu	Dihitung per
GET /catalog/* (kelimanya)	5000	60 detik	per akun
POST /orders/create	5000	60 detik	per akun
GET /orders/:orderId	3	60 detik	per akun + ID pesanan
POST /orders/batch	2	60 detik	per akun
GET /orders	2	60 detik	per akun
GET /account	60	60 detik	per akun
POST /player/validate	kuota cek pemain harian	24 jam	per akun (tanpa header X-RateLimit)

Webhook

Hasil pesanan dikirim otomatis ke endpoint HTTPS yang kamu daftarkan, ditandatangani dengan HMAC-SHA256 atas raw body. Daftar event, daftar header, struktur payload, dan contoh kode verifikasinya ada di halaman ringkasan API.

Baca referensi payload dan signature webhook

Kalau baru pertama kali pakai platform ini, mulai dari ringkasan API top up game untuk reseller, atau baca ringkasan program reseller SHOP2TOPUP untuk tahu cara kerja akun partner.