Dokumentasi API
Buat pesanan Free Fire, Mobile Legends, Magic Chess: Go Go, dan Blood Strike dari perangkat lunak Anda sendiri. Setiap pesanan dibayar oleh akun pemasok Anda sendiri.
Mulai
Autentikasi
Kirim kunci API Anda di header Authorization pada setiap permintaan.
Authorization: Bearer YOUR_API_KEYSimpan kunci di server Anda. Siapa pun yang memilikinya dapat memakai Shell dan Smile Coin di akun Anda, jadi jangan taruh di situs web atau aplikasi ponsel.
Kunci API hanya berlaku di endpoint pesanan dan item di halaman ini.
Daftar kode item
GET/api/items
Mengembalikan apa yang dijual sebuah game sekarang, dibaca langsung lewat akun default Anda, beserta kode item untuk dikirim dalam pesanan.
| Kolom | Catatan |
|---|---|
gamequery · Wajib | Game: freefire, mobilelegends, magicchessgogo, atau bloodstrike. |
regionquery · Opsional | Hanya untuk Free Fire, dan wajib di sana: KH, MY, SG, PH, VN, atau TW. |
| Game | Catatan |
|---|---|
freefire | Free Fire. Kode itemnya membawa wilayah toko: freefire-KH-100. |
mobilelegends | Mobile Legends. Kirim serverId (Zone ID) bersama pesanan. |
magicchessgogo | Magic Chess: Go Go. Kirim serverId bersama pesanan. |
bloodstrike | Blood Strike. Tanpa serverId dan tanpa region. |
curl "https://topupkit.com/api/items?game=freefire®ion=KH" \
-H "Authorization: Bearer YOUR_API_KEY"{
"ok": true,
"data": [
{
"item": "freefire-KH-100",
"name": "100 Diamonds",
"price": "86 Shell",
"costMinorUnits": 15652
},
{
"item": "freefire-KH-weekly_membership",
"name": "Weekly Membership",
"price": "160 Shell",
"costMinorUnits": null
}
]
}Buat pesanan
POST/api/orders
Menerima pesanan dan langsung menjawab dengan status pending. Pembayaran lalu berjalan di latar belakang, biasanya kurang dari satu menit dan paling lama sekitar tiga menit. Dapatkan hasilnya dengan membaca pesanan, atau dari callback. Pesanan yang ditolak tetap pesanan, dengan alasannya.
Permintaan
| Kolom | Catatan |
|---|---|
Authorizationheader · Wajib | Bearer, lalu kunci API Anda. |
Idempotency-Keyheader · Opsional | Nama unik Anda sendiri untuk pesanan ini, hingga 255 karakter. Sangat disarankan. |
itemstring · Wajib | Kode item dari daftar item: freefire-KH-100 untuk Free Fire, yang membawa wilayah toko di dalam kode, atau mobilelegends-22590. Kode ini menunjukkan game pesanan. |
playerIdstring · Wajib | Pemain yang menerima item. Hanya angka, hingga 20. |
serverIdstring · Opsional | Hanya untuk game yang memintanya: Zone ID Mobile Legends atau Server ID Magic Chess: Go Go. Jika tidak, jangan dikirim. |
accountIdstring · Opsional | Opsional. Akun pemasok yang membayar. Tanpanya, akun default Anda untuk pemasok itu (dan wilayah, untuk Free Fire) yang membayar. |
curl -X POST "https://topupkit.com/api/orders" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: my-order-1001" \
-d '{
"item": "freefire-KH-100",
"playerId": "123456789"
}'{
"item": "mobilelegends-22590",
"playerId": "123456789",
"serverId": "2001"
}201 untuk pesanan baru. 200 jika Idempotency-Key ini sudah dipakai: Anda menerima pesanan pertama lagi dan tidak ada pembayaran lagi.
{
"ok": true,
"data": {
"id": "0b6f6c1e-8a57-4f0a-9d3e-1f2a7c4b9e10",
"supplier": "garena",
"game": "freefire",
"item": "freefire-KH-100",
"region": "KH",
"serverId": null,
"playerId": "123456789",
"status": "pending",
"playerNickname": null,
"itemName": null,
"price": null,
"providerReference": null,
"supplierMessage": null,
"failureReason": null,
"createdAt": "2026-01-15T08:30:00.000Z",
"settledAt": null
}
}Objek pesanan
| Kolom | Catatan |
|---|---|
idstring | ID pesanan, untuk dibaca nanti. |
supplierstring | Siapa yang memenuhi pesanan: garena atau smileone. |
gamestring | Game: freefire, mobilelegends, magicchessgogo, atau bloodstrike. |
itemstring | Kode item dari daftar item: freefire-KH-100 untuk Free Fire, yang membawa wilayah toko di dalam kode, atau mobilelegends-22590. Kode ini menunjukkan game pesanan. |
regionstring | null | Wilayah toko Free Fire. Null untuk game lain. |
serverIdstring | null | Server ID yang dikirim bersama pesanan. Null jika game tidak memilikinya. |
playerIdstring | Pemain yang menerima item. Hanya angka, hingga 20. |
statusstring | Lihat Status pesanan. |
playerNicknamestring | null | Nama pemain, setelah pemasok memberikannya. |
itemNamestring | null | Nama item menurut pemasok. Null untuk Free Fire. |
pricestring | null | Yang ditagih atau akan ditagih Garena, sebagai teks, seperti 13 Shell. Null untuk game lain. |
providerReferencestring | null | ID transaksi pemasok, kapan pun diberikan. |
supplierMessagestring | null | Kata-kata pemasok sendiri saat menolak pesanan. |
failureReasonstring | null | Alasan pesanan gagal. Hanya ada jika status adalah failed. |
createdAtstring | Waktu pesanan dibuat (tanggal ISO). |
settledAtstring | null | Kapan jawaban pemasok disimpan (ISO date). Null selama pending. |
Status pesanan
| Status | Arti |
|---|---|
success | Pemasok menerima pesanan dan mengambil Shell atau Smile Coin. |
failed | Pemasok tidak mengambil apa pun. failureReason menjelaskan alasannya. |
unknown | Jawabannya hilang, jadi Shell atau Smile Coin mungkin sudah terpakai atau belum. Periksa riwayat akun Anda sebelum memesan lagi. |
pending | Diterima dan masih dibayar. Baca pesanan lagi, atau tunggu callback. Setelah 10 menit statusnya menjadi unknown. |
Alasan kegagalan
Ada pada pesanan yang gagal. Dalam semua kasus pemasok tidak mengambil apa pun.
| Kode | Arti |
|---|---|
player_not_found | Garena tidak mengenal ID pemain ini. Tidak ada Shell yang terambil. |
player_region_not_allowed | Toko ini tidak bisa menjual ke wilayah pemain ini. Tidak ada Shell yang terambil. |
item_not_available | Item ini tidak tersedia untuk pemain ini saat ini. Tidak ada Shell yang terambil. |
insufficient_shell | Akun Garena ini tidak punya cukup Shell. Tidak ada Shell yang terambil. |
otp_rejected | Garena tidak menerima kode autentikator. Periksa rahasia autentikator akun. Tidak ada Shell yang terambil. |
garena_refused | Garena menolak pesanan ini. Tidak ada Shell yang terambil. |
garena_unavailable | Tidak bisa terhubung ke Garena. Coba lagi sebentar lagi. Tidak ada Shell yang terambil. |
smileone_account_expired | Cookie akun tidak lagi berfungsi. Tempel cookie baru. Tidak ada yang dibayar. |
smileone_refused | SmileOne menolak pesanan ini. Tidak ada yang dibayar. |
smileone_unavailable | SmileOne tidak dapat dihubungi. Tidak ada yang dibayar. |
Baca satu pesanan
GET/api/orders/{id}
Mengembalikan pesanan dengan ID ini. Tanyakan setiap beberapa detik sampai status bukan lagi pending.
Daftar pesanan terbaru
GET/api/orders
Mengembalikan 20 pesanan terbaru Anda, yang dibuat dengan API key atau di situs. Tambahkan ?supplier=garena atau ?supplier=smileone untuk satu pemasok.
Callback
Callback (disebut juga webhook) adalah permintaan yang kami kirim ke server Anda saat pesanan dengan kunci API Anda selesai, jadi Anda tidak perlu terus bertanya. Isinya objek pesanan yang sama, dan hanya datang saat status success, failed, atau unknown. Membaca pesanan juga selalu bisa.
Di halaman kunci API, tekan Callback pada kunci Anda dan masukkan alamat https://. Anda mendapat rahasia tanda tangan satu kali. Tekan Kirim uji coba untuk memeriksa server Anda: uji coba memiliki header X-Callback-Event: test dan pesanan contoh.
POST /your-callback-url
Content-Type: application/json
X-Callback-Event: order.settled
X-Callback-Timestamp: 1768465804
X-Callback-Signature: sha256=5f8d0c…
{
"id": "0b6f6c1e-8a57-4f0a-9d3e-1f2a7c4b9e10",
"supplier": "garena",
"game": "freefire",
"item": "freefire-KH-100",
"region": "KH",
"serverId": null,
"playerId": "123456789",
"status": "success",
"playerNickname": "FF_Player",
"itemName": null,
"price": "86 Shell",
"providerReference": "GARENA_TRANSACTION_ID",
"supplierMessage": null,
"failureReason": null,
"createdAt": "2026-01-15T08:30:00.000Z",
"settledAt": "2026-01-15T08:30:04.000Z"
}Periksa tanda tangan sebelum memercayai callback. Tanda tangan itu adalah HMAC-SHA256 dari timestamp, sebuah titik, dan body persisnya, memakai rahasia tanda tangan Anda.
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the request body exactly as received, before JSON.parse.
const expected = Buffer.from(
"sha256=" +
createHmac("sha256", SIGNING_SECRET)
.update(`${headers["x-callback-timestamp"]}.${rawBody}`)
.digest("hex"),
);
const received = Buffer.from(headers["x-callback-signature"] ?? "");
const age = Date.now() / 1000 - Number(headers["x-callback-timestamp"]);
const genuine =
received.length === expected.length &&
timingSafeEqual(received, expected) &&
Math.abs(age) < 300;Siapa pun yang menemukan alamat Anda bisa mengirim “success” palsu. Tanpa pemeriksaan ini mereka bisa mendapat item gratis.
Jawab dengan status 2xx dalam 10 detik. Jawaban lain akan dicoba lagi, hingga lima kali lagi dalam sekitar enam jam. Anda mungkin menerima pesanan yang sama dua kali, jadi gunakan id pesanan untuk mengabaikan pengulangan. Kami tidak mengikuti pengalihan, dan alamat di jaringan pribadi ditolak.
Mencoba lagi dengan aman
Jika permintaan kehabisan waktu, Anda tidak tahu apakah sudah dibayar. Kirim lagi dengan Idempotency-Key yang sama: pesanan pertama kembali dan tidak ada pembayaran ganda. Tanpa header ini, setiap permintaan adalah pesanan baru dan bisa membayar lagi.
Format respons
Setiap respons berupa JSON dengan kolom ok. Jika ok bernilai true, hasilnya ada di data. Jika false, gunakan error.code: error.message bisa berubah.
{
"ok": false,
"error": {
"code": "UNAUTHORIZED",
"message": "…"
}
}Galat
Pesanan yang ditolak bukan galat: pesanan kembali dengan status failed. Kode ini berarti permintaannya sendiri tidak bisa ditangani.
| Kode | Arti |
|---|---|
400INVALID_JSON | Terjadi masalah saat mengirim ini. Muat ulang halaman dan coba lagi. |
400VALIDATION_ERROR | Ada kolom yang kosong atau salah. error.message menyebutkan masalahnya. |
401UNAUTHORIZED | Kunci API tidak ada, salah, atau sudah dihapus. |
404NOT_FOUND | Pesanan ini tidak ada, atau bukan milik Anda. |
409NO_DEFAULT_ACCOUNT | Belum ada akun yang dipilih untuk membayar pesanan API game ini. Buka halaman Garena atau SmileOne lalu tekan “Pakai untuk pesanan API” pada satu akun. |
409GARENA_ACCOUNT_NOT_READY_FOR_ORDERS | Akun Garena ini belum diatur untuk pesanan. Masukkan UID dan rahasia autentikatornya dulu. |
413PAYLOAD_TOO_LARGE | Ini terlalu besar untuk dikirim. Perpendek catatan atau kolom panjang lainnya lalu coba lagi. |
500INTERNAL_ERROR | Terjadi masalah di pihak kami. Coba lagi sebentar lagi. |