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

Pilih akun yang membayar pesanan API: buka halamannya lalu tekan “Pakai untuk pesanan API”. Garena perlu satu untuk setiap wilayah. Garena · SmileOne
Minta kode item yang dijual sebuah game sekarang dengan permintaan daftar item di bawah.
Kirim pesanan pertama Anda dengan permintaan di bawah.

Autentikasi

Kirim kunci API Anda di header Authorization pada setiap permintaan.

Authorization
Authorization: Bearer YOUR_API_KEY

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

KolomCatatan
gamequery · WajibGame: freefire, mobilelegends, magicchessgogo, atau bloodstrike.
regionquery · OpsionalHanya untuk Free Fire, dan wajib di sana: KH, MY, SG, PH, VN, atau TW.
GameCatatan
freefireFree Fire. Kode itemnya membawa wilayah toko: freefire-KH-100.
mobilelegendsMobile Legends. Kirim serverId (Zone ID) bersama pesanan.
magicchessgogoMagic Chess: Go Go. Kirim serverId bersama pesanan.
bloodstrikeBlood Strike. Tanpa serverId dan tanpa 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 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

KolomCatatan
Authorizationheader · WajibBearer, lalu kunci API Anda.
Idempotency-Keyheader · OpsionalNama unik Anda sendiri untuk pesanan ini, hingga 255 karakter. Sangat disarankan.
itemstring · WajibKode 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 · WajibPemain yang menerima item. Hanya angka, hingga 20.
serverIdstring · OpsionalHanya untuk game yang memintanya: Zone ID Mobile Legends atau Server ID Magic Chess: Go Go. Jika tidak, jangan dikirim.
accountIdstring · OpsionalOpsional. Akun pemasok yang membayar. Tanpanya, akun default Anda untuk pemasok 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 baru. 200 jika Idempotency-Key ini sudah dipakai: Anda menerima pesanan pertama lagi dan tidak ada pembayaran 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

KolomCatatan
idstringID pesanan, untuk dibaca nanti.
supplierstringSiapa yang memenuhi pesanan: garena atau smileone.
gamestringGame: freefire, mobilelegends, magicchessgogo, atau bloodstrike.
itemstringKode 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 | nullWilayah toko Free Fire. Null untuk game lain.
serverIdstring | nullServer ID yang dikirim bersama pesanan. Null jika game tidak memilikinya.
playerIdstringPemain yang menerima item. Hanya angka, hingga 20.
statusstringLihat Status pesanan.
playerNicknamestring | nullNama pemain, setelah pemasok memberikannya.
itemNamestring | nullNama item menurut pemasok. Null untuk Free Fire.
pricestring | nullYang ditagih atau akan ditagih Garena, sebagai teks, seperti 13 Shell. Null untuk game lain.
providerReferencestring | nullID transaksi pemasok, kapan pun diberikan.
supplierMessagestring | nullKata-kata pemasok sendiri saat menolak pesanan.
failureReasonstring | nullAlasan pesanan gagal. Hanya ada jika status adalah failed.
createdAtstringWaktu pesanan dibuat (tanggal ISO).
settledAtstring | nullKapan jawaban pemasok disimpan (ISO date). Null selama pending.

Status pesanan

StatusArti
successPemasok menerima pesanan dan mengambil Shell atau Smile Coin.
failedPemasok tidak mengambil apa pun. failureReason menjelaskan alasannya.
unknownJawabannya hilang, jadi Shell atau Smile Coin mungkin sudah terpakai atau belum. Periksa riwayat akun Anda sebelum memesan lagi.
pendingDiterima 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.

KodeArti
player_not_foundGarena tidak mengenal ID pemain ini. Tidak ada Shell yang terambil.
player_region_not_allowedToko ini tidak bisa menjual ke wilayah pemain ini. Tidak ada Shell yang terambil.
item_not_availableItem ini tidak tersedia untuk pemain ini saat ini. Tidak ada Shell yang terambil.
insufficient_shellAkun Garena ini tidak punya cukup Shell. Tidak ada Shell yang terambil.
otp_rejectedGarena tidak menerima kode autentikator. Periksa rahasia autentikator akun. Tidak ada Shell yang terambil.
garena_refusedGarena menolak pesanan ini. Tidak ada Shell yang terambil.
garena_unavailableTidak bisa terhubung ke Garena. Coba lagi sebentar lagi. Tidak ada Shell yang terambil.
smileone_account_expiredCookie akun tidak lagi berfungsi. Tempel cookie baru. Tidak ada yang dibayar.
smileone_refusedSmileOne menolak pesanan ini. Tidak ada yang dibayar.
smileone_unavailableSmileOne 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.

Yang diterima server Anda
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.

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;

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.

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

KodeArti
400INVALID_JSONTerjadi masalah saat mengirim ini. Muat ulang halaman dan coba lagi.
400VALIDATION_ERRORAda kolom yang kosong atau salah. error.message menyebutkan masalahnya.
401UNAUTHORIZEDKunci API tidak ada, salah, atau sudah dihapus.
404NOT_FOUNDPesanan ini tidak ada, atau bukan milik Anda.
409NO_DEFAULT_ACCOUNTBelum 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_ORDERSAkun Garena ini belum diatur untuk pesanan. Masukkan UID dan rahasia autentikatornya dulu.
413PAYLOAD_TOO_LARGEIni terlalu besar untuk dikirim. Perpendek catatan atau kolom panjang lainnya lalu coba lagi.
500INTERNAL_ERRORTerjadi masalah di pihak kami. Coba lagi sebentar lagi.