Dokumentasyon ng API

Mag-order ng Free Fire, Mobile Legends, Magic Chess: Go Go at Blood Strike mula sa sarili mong software. Bawat order ay binabayaran ng sarili mong supplier account.

Magsimula

Piliin kung aling account ang nagbabayad ng mga API order: buksan ang page nito at pindutin ang “Gamitin sa mga API order”. Kailangan ng Garena ng isa bawat rehiyon. Garena · SmileOne
Kunin ang mga item code na ibinebenta ngayon ng isang laro gamit ang item list request sa ibaba.
Ipadala ang una mong order gamit ang request sa ibaba.

Authentication

Ipadala ang iyong API key sa Authorization header ng bawat request.

Authorization
Authorization: Bearer YOUR_API_KEY

Itago ang key sa server mo. Sinumang may hawak nito ay makagagastos ng Shell at Smile Coin sa mga account mo, kaya huwag itong ilagay sa website o phone app.

Gumagana lang ang API key sa mga order at item endpoint sa page na ito.

Listahan ng item code

GET/api/items

Ibinabalik ang ibinebenta ngayon ng isang laro, binabasa nang live sa default account mo, kasama ang item code na ipapadala sa order.

FieldMga tala
gamequery · KailanganAng laro: freefire, mobilelegends, magicchessgogo o bloodstrike.
regionquery · OpsyonalPara lang sa Free Fire, at kailangan doon: KH, MY, SG, PH, VN o TW.
LaroMga tala
freefireFree Fire. Ang item code nito ay may shop region: freefire-KH-100.
mobilelegendsMobile Legends. Ipadala ang serverId (ang Zone ID) kasama ng order.
magicchessgogoMagic Chess: Go Go. Ipadala ang serverId kasama ng order.
bloodstrikeBlood Strike. Walang serverId at walang region.
Halimbawang request
curl "https://topupkit.com/api/items?game=freefire&region=KH" \
  -H "Authorization: Bearer YOUR_API_KEY"
Halimbawang response
{
  "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
    }
  ]
}

Mag-order

POST/api/orders

Tinatanggap ang order at sumasagot agad ng status pending. Pagkatapos, tumatakbo sa background ang bayad, karaniwang wala pang isang minuto at hanggang mga tatlong minuto. Kunin ang resulta sa pagbasa ng order, o mula sa callback. Order pa rin ang tinanggihang order, kasama ang dahilan nito.

Request

FieldMga tala
Authorizationheader · KailanganBearer, saka ang iyong API key.
Idempotency-Keyheader · OpsyonalSarili mong natatanging pangalan para sa order na ito, hanggang 255 character. Lubos na inirerekomenda.
itemstring · KailanganAng item code mula sa item list: freefire-KH-100 para sa Free Fire, na may shop region sa code, o mobilelegends-22590. Sinasabi nito kung para saang laro ang order.
playerIdstring · KailanganAng player na tatanggap ng item. Numero lang, hanggang 20.
serverIdstring · OpsyonalPara lang sa mga larong humihingi nito: ang Zone ID ng Mobile Legends o ang Server ID ng Magic Chess: Go Go. Kung hindi, huwag isama.
accountIdstring · OpsyonalOpsyonal. Ang supplier account na magbabayad. Kung wala ito, ang default account mo para sa supplier na iyon (at rehiyon, para sa Free Fire) ang magbabayad.
Halimbawang request
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"
  }'
Halimbawang body para sa Mobile Legends
{
  "item": "mobilelegends-22590",
  "playerId": "123456789",
  "serverId": "2001"
}

201 para sa bagong order. 200 kapag nagamit na ang Idempotency-Key na ito: ibabalik ang unang order at walang panibagong bayad.

Halimbawang response
{
  "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
  }
}

Ang order object

FieldMga tala
idstringAng ID ng order, para mabasa ito mamaya.
supplierstringSino ang tumupad sa order: garena o smileone.
gamestringAng laro: freefire, mobilelegends, magicchessgogo o bloodstrike.
itemstringAng item code mula sa item list: freefire-KH-100 para sa Free Fire, na may shop region sa code, o mobilelegends-22590. Sinasabi nito kung para saang laro ang order.
regionstring | nullAng shop region ng Free Fire. Null sa ibang laro.
serverIdstring | nullAng server ID na ipinadala kasama ng order. Null kapag wala ang laro nito.
playerIdstringAng player na tatanggap ng item. Numero lang, hanggang 20.
statusstringTingnan ang Mga status ng order.
playerNicknamestring | nullAng pangalan ng player, kapag naibigay na ng supplier.
itemNamestring | nullAng sariling pangalan ng supplier para sa item. Null sa Free Fire.
pricestring | nullAng siningil o sisingilin ng Garena, bilang text, gaya ng 13 Shell. Null sa ibang laro.
providerReferencestring | nullAng transaction ID ng supplier, tuwing nagbigay ito.
supplierMessagestring | nullAng sariling salita ng supplier kapag tinanggihan nito ang order.
failureReasonstring | nullKung bakit pumalya ang order. Mayroon lang kapag failed ang status.
createdAtstringKung kailan ginawa ang order (ISO date).
settledAtstring | nullKailan na-save ang sagot ng supplier (ISO date). Null habang pending.

Mga status ng order

StatusKahulugan
successTinanggap ng supplier ang order at kinuha ang Shell o Smile Coin.
failedWalang kinuha ang supplier. Sinasabi ng failureReason kung bakit.
unknownNawala ang sagot, kaya maaaring nagastos o hindi pa ang Shell o Smile Coin. Tingnan ang history ng account mo bago mag-order ulit.
pendingTinanggap at binabayaran pa. Basahin ulit ang order, o hintayin ang callback. Pagkalipas ng 10 minuto, magiging unknown ito.

Mga dahilan ng pagpalya

Nakalagay sa failed na order. Sa lahat ng kaso, walang kinuha ang supplier.

CodeKahulugan
player_not_foundHindi kilala ng Garena ang player ID na ito. Walang Shell na nakuha.
player_region_not_allowedHindi makapagbenta ang shop na ito sa rehiyon ng player na ito. Walang Shell na nakuha.
item_not_availableHindi available ang item na ito para sa player na ito ngayon. Walang Shell na nakuha.
insufficient_shellKulang ang Shell ng Garena account na ito. Walang Shell na nakuha.
otp_rejectedHindi tinanggap ng Garena ang authenticator code. Suriin ang authenticator secret ng account. Walang Shell na nakuha.
garena_refusedTinanggihan ng Garena ang order na ito. Walang Shell na nakuha.
garena_unavailableHindi maabot ang Garena. Subukan muli sa ilang sandali. Walang Shell na nakuha.
smileone_account_expiredHindi na gumagana ang cookie ng account. Mag-paste ng bago. Walang bayad na nakuha.
smileone_refusedTinanggihan ng SmileOne ang order na ito. Walang bayad na nakuha.
smileone_unavailableHindi maabot ang SmileOne. Walang bayad na nakuha.

Basahin ang isang order

GET/api/orders/{id}

Ibinabalik ang order na may ganitong ID. Magtanong kada ilang segundo hanggang hindi na pending ang status.

Listahan ng mga bagong order

GET/api/orders

Ibinabalik ang iyong pinakabagong 20 order, na inilagay ng API key o sa site. Idagdag ang ?supplier=garena o ?supplier=smileone para sa isang supplier.

Mga callback

Ang callback (tinatawag ding webhook) ay request na ipinapadala namin sa iyong server kapag natapos ang order na ginawa gamit ang iyong API key, kaya hindi mo kailangang paulit-ulit magtanong. Ginagamit nito ang parehong order object, at dumarating lang kapag success, failed o unknown ang status. Gumagana pa rin ang pagbasa ng order.

Sa page ng mga API key, pindutin ang Callback sa iyong key at maglagay ng https:// na address. Isang beses ka lang makakakuha ng signing secret. Pindutin ang Magpadala ng test para suriin ang iyong server: may header na X-Callback-Event: test ang test, at isang halimbawang order.

Ang natatanggap ng iyong server
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"
}

Suriin ang signature bago pagkatiwalaan ang callback. Ito ang HMAC-SHA256 ng timestamp, isang tuldok, at ng eksaktong body, gamit ang iyong signing secret.

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;

Sinumang makakita ng iyong address ay maaaring magpadala ng pekeng “success”. Kung walang ganitong pagsusuri, maaari silang makakuha ng item nang libre.

Sumagot ng 2xx status sa loob ng 10 segundo. Susubukan ulit ang ibang sagot, hanggang limang beses pa sa loob ng mga anim na oras. Maaari mong matanggap ang parehong order nang dalawang beses, kaya gamitin ang id ng order para balewalain ang mga ulit. Hindi kami sumusunod sa redirect, at tinatanggihan ang mga address sa pribadong network.

Ligtas na pag-ulit

Kapag nag-timeout ang request, hindi mo malalaman kung nabayaran ito. Ipadala ulit gamit ang parehong Idempotency-Key: babalik ang unang order at walang dobleng bayad. Kung walang header na ito, bagong order ang bawat request at maaaring magbayad ulit.

Format ng response

Bawat response ay JSON na may ok na field. Kapag true ang ok, nasa data ang resulta. Kapag false, gamitin ang error.code: maaaring magbago ang error.message.

error
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "…"
  }
}

Mga error

Hindi error ang tinanggihang order: bumabalik ito na may status na failed. Ang mga code na ito ay nangangahulugang hindi maproseso ang mismong request.

CodeKahulugan
400INVALID_JSONNagkaproblema sa pagpapadala nito. I-refresh ang pahina at subukan muli.
400VALIDATION_ERRORMay field na kulang o mali. Sinasabi ng error.message ang problema.
401UNAUTHORIZEDWala, mali, o tinanggal na ang API key.
404NOT_FOUNDWala ang order na ito, o hindi ito sa iyo.
409NO_DEFAULT_ACCOUNTWalang napiling account na magbabayad ng mga API order para sa larong ito. Buksan ang page ng Garena o SmileOne at pindutin ang “Gamitin sa mga API order” sa isang account.
409GARENA_ACCOUNT_NOT_READY_FOR_ORDERSHindi pa naka-set up para sa mga order ang Garena account na ito. Ilagay muna ang UID at authenticator secret nito.
413PAYLOAD_TOO_LARGEMasyadong malaki ito para ipadala. Paikliin ang tala o iba pang mahabang field at subukan muli.
500INTERNAL_ERRORNagkaproblema sa panig namin. Subukan muli sa ilang sandali.