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

Pilih akaun yang membayar pesanan API: buka halamannya dan tekan “Guna untuk pesanan API”. Garena perlukan satu bagi setiap wilayah. Garena · SmileOne
Minta kod item yang dijual oleh sesuatu permainan sekarang dengan permintaan senarai item di bawah.
Hantar pesanan pertama anda dengan permintaan di bawah.

Pengesahan

Hantar kunci API anda dalam header Authorization setiap permintaan.

Authorization
Authorization: Bearer YOUR_API_KEY

Simpan 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.

MedanNota
gamequery · WajibPermainan: freefire, mobilelegends, magicchessgogo atau bloodstrike.
regionquery · PilihanUntuk Free Fire sahaja, dan wajib di situ: KH, MY, SG, PH, VN atau TW.
PermainanNota
freefireFree Fire. Kod itemnya membawa wilayah kedai: freefire-KH-100.
mobilelegendsMobile Legends. Hantar serverId (Zone ID) bersama pesanan.
magicchessgogoMagic Chess: Go Go. Hantar serverId bersama pesanan.
bloodstrikeBlood Strike. Tiada serverId dan tiada region.
Contoh permintaan
curl "https://topupkit.com/api/items?game=freefire&region=KH" \
  -H "Authorization: Bearer YOUR_API_KEY"
Contoh respons
{
  "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

MedanNota
Authorizationheader · WajibBearer, kemudian kunci API anda.
Idempotency-Keyheader · PilihanNama unik anda sendiri untuk pesanan ini, sehingga 255 aksara. Sangat disyorkan.
itemstring · WajibKod 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 · WajibPemain yang menerima item. Digit sahaja, sehingga 20.
serverIdstring · PilihanHanya untuk permainan yang memintanya: Zone ID Mobile Legends atau Server ID Magic Chess: Go Go. Jika tidak, jangan hantar.
accountIdstring · PilihanPilihan. Akaun pembekal yang membayar. Tanpanya, akaun lalai anda untuk pembekal itu (dan wilayah, untuk Free Fire) yang membayar.
Contoh permintaan
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"
  }'
Contoh body untuk Mobile Legends
{
  "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.

Contoh respons
{
  "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

MedanNota
idstringID pesanan, untuk dibaca kemudian.
supplierstringSiapa yang memenuhi pesanan: garena atau smileone.
gamestringPermainan: freefire, mobilelegends, magicchessgogo atau bloodstrike.
itemstringKod 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 | nullWilayah kedai Free Fire. Null untuk permainan lain.
serverIdstring | nullServer ID yang dihantar bersama pesanan. Null jika permainan tiada.
playerIdstringPemain yang menerima item. Digit sahaja, sehingga 20.
statusstringLihat Status pesanan.
playerNicknamestring | nullNama pemain, setelah pembekal memberikannya.
itemNamestring | nullNama item mengikut pembekal. Null untuk Free Fire.
pricestring | nullApa yang Garena caj atau akan caj, sebagai teks, seperti 13 Shell. Null untuk permainan lain.
providerReferencestring | nullID transaksi pembekal, bila-bila ia diberikan.
supplierMessagestring | nullKata-kata pembekal sendiri apabila ia menolak pesanan.
failureReasonstring | nullSebab pesanan gagal. Ada hanya apabila status ialah failed.
createdAtstringMasa pesanan dicipta (tarikh ISO).
settledAtstring | nullBila jawapan pembekal disimpan (ISO date). Null semasa pending.

Status pesanan

StatusMaksud
successPembekal menerima pesanan dan mengambil Shell atau Smile Coin.
failedPembekal tidak mengambil apa-apa. failureReason menyatakan sebabnya.
unknownJawapan hilang, jadi Shell atau Smile Coin mungkin sudah atau belum dibelanjakan. Semak sejarah akaun anda sebelum memesan semula.
pendingDiterima 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.

KodMaksud
player_not_foundGarena tidak mengenali ID pemain ini. Tiada Shell diambil.
player_region_not_allowedKedai ini tidak boleh menjual kepada rantau pemain ini. Tiada Shell diambil.
item_not_availableItem ini tidak tersedia untuk pemain ini sekarang. Tiada Shell diambil.
insufficient_shellAkaun Garena ini tidak cukup Shell. Tiada Shell diambil.
otp_rejectedGarena tidak menerima kod pengesah. Semak rahsia pengesah akaun. Tiada Shell diambil.
garena_refusedGarena menolak pesanan ini. Tiada Shell diambil.
garena_unavailableTidak dapat menghubungi Garena. Cuba lagi sebentar lagi. Tiada Shell diambil.
smileone_account_expiredCookie akaun tidak lagi berfungsi. Tampal cookie baharu. Tiada apa-apa dibayar.
smileone_refusedSmileOne menolak pesanan ini. Tiada apa-apa dibayar.
smileone_unavailableSmileOne 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.

Apa yang pelayan anda terima
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.

Node.js
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.

error
{
  "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.

KodMaksud
400INVALID_JSONBerlaku masalah semasa menghantar ini. Muat semula halaman dan cuba lagi.
400VALIDATION_ERRORSatu medan tiada atau salah. error.message menyatakan masalahnya.
401UNAUTHORIZEDKunci API tiada, salah atau telah dibuang.
404NOT_FOUNDPesanan ini tidak wujud, atau bukan milik anda.
409NO_DEFAULT_ACCOUNTTiada 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_ORDERSAkaun Garena ini belum disediakan untuk pesanan. Masukkan UID dan rahsia pengesahnya dahulu.
413PAYLOAD_TOO_LARGEIni terlalu besar untuk dihantar. Pendekkan nota atau ruangan panjang lain dan cuba lagi.
500INTERNAL_ERRORBerlaku masalah di pihak kami. Cuba lagi sebentar lagi.