Dokumentasi API
Buat pesanan Free Fire, Mobile Legends, Magic Chess: Go Go dan Blood Strike daripada perisian anda sendiri. Setiap pesanan dibayar oleh akaun pembekal anda sendiri.
Mula
Pengesahan
Hantar kunci API anda dalam header Authorization setiap permintaan.
Authorization: Bearer YOUR_API_KEYSimpan kunci di pelayan anda. Sesiapa yang memilikinya boleh membelanjakan Shell dan Smile Coin dalam akaun anda, jadi jangan letakkannya dalam laman web atau aplikasi telefon.
Kunci API hanya berfungsi pada endpoint pesanan dan item di halaman ini.
Senarai kod item
GET/api/items
Memulangkan apa yang dijual oleh sesuatu permainan sekarang, dibaca terus melalui akaun lalai anda, bersama kod item untuk dihantar dalam pesanan.
| Medan | Nota |
|---|---|
gamequery · Wajib | Permainan: freefire, mobilelegends, magicchessgogo atau bloodstrike. |
regionquery · Pilihan | Untuk Free Fire sahaja, dan wajib di situ: KH, MY, SG, PH, VN atau TW. |
| Permainan | Nota |
|---|---|
freefire | Free Fire. Kod itemnya membawa wilayah kedai: freefire-KH-100. |
mobilelegends | Mobile Legends. Hantar serverId (Zone ID) bersama pesanan. |
magicchessgogo | Magic Chess: Go Go. Hantar serverId bersama pesanan. |
bloodstrike | Blood Strike. Tiada serverId dan tiada 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 menjawab serta-merta dengan status pending. Pembayaran kemudian berjalan di latar belakang, biasanya kurang daripada seminit dan paling lama kira-kira tiga minit. Dapatkan keputusan dengan membaca pesanan, atau melalui callback. Pesanan yang ditolak tetap pesanan, dengan sebabnya.
Permintaan
| Medan | Nota |
|---|---|
Authorizationheader · Wajib | Bearer, kemudian kunci API anda. |
Idempotency-Keyheader · Pilihan | Nama unik anda sendiri untuk pesanan ini, sehingga 255 aksara. Sangat disyorkan. |
itemstring · Wajib | Kod item daripada senarai item: freefire-KH-100 untuk Free Fire, yang membawa wilayah kedai dalam kod, atau mobilelegends-22590. Ia menunjukkan permainan pesanan itu. |
playerIdstring · Wajib | Pemain yang menerima item. Digit sahaja, sehingga 20. |
serverIdstring · Pilihan | Hanya untuk permainan yang memintanya: Zone ID Mobile Legends atau Server ID Magic Chess: Go Go. Jika tidak, jangan hantar. |
accountIdstring · Pilihan | Pilihan. Akaun pembekal yang membayar. Tanpanya, akaun lalai anda untuk pembekal 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 baharu. 200 apabila Idempotency-Key ini sudah digunakan: anda mendapat pesanan pertama semula dan tiada bayaran 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
| Medan | Nota |
|---|---|
idstring | ID pesanan, untuk dibaca kemudian. |
supplierstring | Siapa yang memenuhi pesanan: garena atau smileone. |
gamestring | Permainan: freefire, mobilelegends, magicchessgogo atau bloodstrike. |
itemstring | Kod item daripada senarai item: freefire-KH-100 untuk Free Fire, yang membawa wilayah kedai dalam kod, atau mobilelegends-22590. Ia menunjukkan permainan pesanan itu. |
regionstring | null | Wilayah kedai Free Fire. Null untuk permainan lain. |
serverIdstring | null | Server ID yang dihantar bersama pesanan. Null jika permainan tiada. |
playerIdstring | Pemain yang menerima item. Digit sahaja, sehingga 20. |
statusstring | Lihat Status pesanan. |
playerNicknamestring | null | Nama pemain, setelah pembekal memberikannya. |
itemNamestring | null | Nama item mengikut pembekal. Null untuk Free Fire. |
pricestring | null | Apa yang Garena caj atau akan caj, sebagai teks, seperti 13 Shell. Null untuk permainan lain. |
providerReferencestring | null | ID transaksi pembekal, bila-bila ia diberikan. |
supplierMessagestring | null | Kata-kata pembekal sendiri apabila ia menolak pesanan. |
failureReasonstring | null | Sebab pesanan gagal. Ada hanya apabila status ialah failed. |
createdAtstring | Masa pesanan dicipta (tarikh ISO). |
settledAtstring | null | Bila jawapan pembekal disimpan (ISO date). Null semasa pending. |
Status pesanan
| Status | Maksud |
|---|---|
success | Pembekal menerima pesanan dan mengambil Shell atau Smile Coin. |
failed | Pembekal tidak mengambil apa-apa. failureReason menyatakan sebabnya. |
unknown | Jawapan hilang, jadi Shell atau Smile Coin mungkin sudah atau belum dibelanjakan. Semak sejarah akaun anda sebelum memesan semula. |
pending | Diterima dan masih dibayar. Baca pesanan lagi, atau tunggu callback. Selepas 10 minit ia menjadi unknown. |
Sebab kegagalan
Ada pada pesanan yang gagal. Dalam setiap kes pembekal tidak mengambil apa-apa.
| Kod | Maksud |
|---|---|
player_not_found | Garena tidak mengenali ID pemain ini. Tiada Shell diambil. |
player_region_not_allowed | Kedai ini tidak boleh menjual kepada rantau pemain ini. Tiada Shell diambil. |
item_not_available | Item ini tidak tersedia untuk pemain ini sekarang. Tiada Shell diambil. |
insufficient_shell | Akaun Garena ini tidak cukup Shell. Tiada Shell diambil. |
otp_rejected | Garena tidak menerima kod pengesah. Semak rahsia pengesah akaun. Tiada Shell diambil. |
garena_refused | Garena menolak pesanan ini. Tiada Shell diambil. |
garena_unavailable | Tidak dapat menghubungi Garena. Cuba lagi sebentar lagi. Tiada Shell diambil. |
smileone_account_expired | Cookie akaun tidak lagi berfungsi. Tampal cookie baharu. Tiada apa-apa dibayar. |
smileone_refused | SmileOne menolak pesanan ini. Tiada apa-apa dibayar. |
smileone_unavailable | SmileOne tidak dapat dihubungi. Tiada apa-apa dibayar. |
Baca satu pesanan
GET/api/orders/{id}
Memulangkan pesanan dengan ID ini. Tanya setiap beberapa saat sehingga status bukan lagi pending.
Senarai pesanan terkini
GET/api/orders
Mengembalikan 20 pesanan terbaharu anda, yang dibuat dengan API key atau di laman. Tambah ?supplier=garena atau ?supplier=smileone untuk satu pembekal.
Callback
Callback (juga dipanggil webhook) ialah permintaan yang kami hantar ke pelayan anda apabila pesanan dengan kunci API anda selesai, supaya anda tidak perlu terus bertanya. Ia menggunakan objek pesanan yang sama, dan hanya datang apabila status ialah success, failed atau unknown. Membaca pesanan juga sentiasa berfungsi.
Di halaman kunci API, tekan Callback pada kunci anda dan masukkan alamat https://. Anda mendapat rahsia tandatangan sekali sahaja. Tekan Hantar ujian untuk menyemak pelayan anda: ujian itu mempunyai 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"
}Semak tandatangan sebelum mempercayai callback. Ia ialah HMAC-SHA256 bagi timestamp, satu titik, dan body yang tepat, menggunakan rahsia tandatangan 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;Sesiapa yang menemui alamat anda boleh menghantar “success” palsu. Tanpa semakan ini mereka boleh mendapat item secara percuma.
Jawab dengan status 2xx dalam masa 10 saat. Jawapan lain akan dicuba semula, sehingga lima kali lagi dalam kira-kira enam jam. Anda mungkin menerima pesanan yang sama dua kali, jadi gunakan id pesanan untuk mengabaikan ulangan. Kami tidak mengikut lencongan, dan alamat pada rangkaian peribadi ditolak.
Cuba semula dengan selamat
Jika permintaan tamat masa, anda tidak dapat tahu sama ada ia sudah dibayar. Hantar semula dengan Idempotency-Key yang sama: pesanan pertama dipulangkan dan tiada bayaran dua kali. Tanpa header ini, setiap permintaan ialah pesanan baharu dan boleh membayar lagi.
Format respons
Setiap respons ialah JSON dengan medan ok. Apabila ok ialah true, hasilnya dalam data. Apabila false, gunakan error.code: error.message boleh berubah.
{
"ok": false,
"error": {
"code": "UNAUTHORIZED",
"message": "…"
}
}Ralat
Pesanan yang ditolak bukan ralat: ia kembali dengan status failed. Kod ini bermaksud permintaan itu sendiri tidak dapat dikendalikan.
| Kod | Maksud |
|---|---|
400INVALID_JSON | Berlaku masalah semasa menghantar ini. Muat semula halaman dan cuba lagi. |
400VALIDATION_ERROR | Satu medan tiada atau salah. error.message menyatakan masalahnya. |
401UNAUTHORIZED | Kunci API tiada, salah atau telah dibuang. |
404NOT_FOUND | Pesanan ini tidak wujud, atau bukan milik anda. |
409NO_DEFAULT_ACCOUNT | Tiada akaun dipilih untuk membayar pesanan API bagi permainan ini. Buka halaman Garena atau SmileOne dan tekan “Guna untuk pesanan API” pada satu akaun. |
409GARENA_ACCOUNT_NOT_READY_FOR_ORDERS | Akaun Garena ini belum disediakan untuk pesanan. Masukkan UID dan rahsia pengesahnya dahulu. |
413PAYLOAD_TOO_LARGE | Ini terlalu besar untuk dihantar. Pendekkan nota atau ruangan panjang lain dan cuba lagi. |
500INTERNAL_ERROR | Berlaku masalah di pihak kami. Cuba lagi sebentar lagi. |