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
Authentication
Ipadala ang iyong API key sa Authorization header ng bawat request.
Authorization: Bearer YOUR_API_KEYItago 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.
| Field | Mga tala |
|---|---|
gamequery · Kailangan | Ang laro: freefire, mobilelegends, magicchessgogo o bloodstrike. |
regionquery · Opsyonal | Para lang sa Free Fire, at kailangan doon: KH, MY, SG, PH, VN o TW. |
| Laro | Mga tala |
|---|---|
freefire | Free Fire. Ang item code nito ay may shop region: freefire-KH-100. |
mobilelegends | Mobile Legends. Ipadala ang serverId (ang Zone ID) kasama ng order. |
magicchessgogo | Magic Chess: Go Go. Ipadala ang serverId kasama ng order. |
bloodstrike | Blood Strike. Walang serverId at walang 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
}
]
}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
| Field | Mga tala |
|---|---|
Authorizationheader · Kailangan | Bearer, saka ang iyong API key. |
Idempotency-Keyheader · Opsyonal | Sarili mong natatanging pangalan para sa order na ito, hanggang 255 character. Lubos na inirerekomenda. |
itemstring · Kailangan | Ang 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 · Kailangan | Ang player na tatanggap ng item. Numero lang, hanggang 20. |
serverIdstring · Opsyonal | Para 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 · Opsyonal | Opsyonal. 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. |
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 para sa bagong order. 200 kapag nagamit na ang Idempotency-Key na ito: ibabalik ang unang order at walang panibagong bayad.
{
"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
| Field | Mga tala |
|---|---|
idstring | Ang ID ng order, para mabasa ito mamaya. |
supplierstring | Sino ang tumupad sa order: garena o smileone. |
gamestring | Ang laro: freefire, mobilelegends, magicchessgogo o bloodstrike. |
itemstring | Ang 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 | null | Ang shop region ng Free Fire. Null sa ibang laro. |
serverIdstring | null | Ang server ID na ipinadala kasama ng order. Null kapag wala ang laro nito. |
playerIdstring | Ang player na tatanggap ng item. Numero lang, hanggang 20. |
statusstring | Tingnan ang Mga status ng order. |
playerNicknamestring | null | Ang pangalan ng player, kapag naibigay na ng supplier. |
itemNamestring | null | Ang sariling pangalan ng supplier para sa item. Null sa Free Fire. |
pricestring | null | Ang siningil o sisingilin ng Garena, bilang text, gaya ng 13 Shell. Null sa ibang laro. |
providerReferencestring | null | Ang transaction ID ng supplier, tuwing nagbigay ito. |
supplierMessagestring | null | Ang sariling salita ng supplier kapag tinanggihan nito ang order. |
failureReasonstring | null | Kung bakit pumalya ang order. Mayroon lang kapag failed ang status. |
createdAtstring | Kung kailan ginawa ang order (ISO date). |
settledAtstring | null | Kailan na-save ang sagot ng supplier (ISO date). Null habang pending. |
Mga status ng order
| Status | Kahulugan |
|---|---|
success | Tinanggap ng supplier ang order at kinuha ang Shell o Smile Coin. |
failed | Walang kinuha ang supplier. Sinasabi ng failureReason kung bakit. |
unknown | Nawala ang sagot, kaya maaaring nagastos o hindi pa ang Shell o Smile Coin. Tingnan ang history ng account mo bago mag-order ulit. |
pending | Tinanggap 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.
| Code | Kahulugan |
|---|---|
player_not_found | Hindi kilala ng Garena ang player ID na ito. Walang Shell na nakuha. |
player_region_not_allowed | Hindi makapagbenta ang shop na ito sa rehiyon ng player na ito. Walang Shell na nakuha. |
item_not_available | Hindi available ang item na ito para sa player na ito ngayon. Walang Shell na nakuha. |
insufficient_shell | Kulang ang Shell ng Garena account na ito. Walang Shell na nakuha. |
otp_rejected | Hindi tinanggap ng Garena ang authenticator code. Suriin ang authenticator secret ng account. Walang Shell na nakuha. |
garena_refused | Tinanggihan ng Garena ang order na ito. Walang Shell na nakuha. |
garena_unavailable | Hindi maabot ang Garena. Subukan muli sa ilang sandali. Walang Shell na nakuha. |
smileone_account_expired | Hindi na gumagana ang cookie ng account. Mag-paste ng bago. Walang bayad na nakuha. |
smileone_refused | Tinanggihan ng SmileOne ang order na ito. Walang bayad na nakuha. |
smileone_unavailable | Hindi 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.
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.
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.
{
"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.
| Code | Kahulugan |
|---|---|
400INVALID_JSON | Nagkaproblema sa pagpapadala nito. I-refresh ang pahina at subukan muli. |
400VALIDATION_ERROR | May field na kulang o mali. Sinasabi ng error.message ang problema. |
401UNAUTHORIZED | Wala, mali, o tinanggal na ang API key. |
404NOT_FOUND | Wala ang order na ito, o hindi ito sa iyo. |
409NO_DEFAULT_ACCOUNT | Walang 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_ORDERS | Hindi pa naka-set up para sa mga order ang Garena account na ito. Ilagay muna ang UID at authenticator secret nito. |
413PAYLOAD_TOO_LARGE | Masyadong malaki ito para ipadala. Paikliin ang tala o iba pang mahabang field at subukan muli. |
500INTERNAL_ERROR | Nagkaproblema sa panig namin. Subukan muli sa ilang sandali. |