Tài liệu API

Đặt đơn Free Fire, Mobile Legends, Magic Chess: Go Go và Blood Strike từ phần mềm của bạn. Mỗi đơn được trả bằng tài khoản nhà cung cấp của chính bạn.

Bắt đầu

Chọn tài khoản trả tiền cho đơn API: mở trang của tài khoản đó và nhấn “Dùng cho đơn API”. Garena cần một tài khoản cho mỗi khu vực. Garena · SmileOne
Lấy mã vật phẩm mà một game đang bán bằng yêu cầu danh sách vật phẩm bên dưới.
Gửi đơn đầu tiên bằng yêu cầu bên dưới.

Xác thực

Gửi khóa API trong header Authorization của mọi yêu cầu.

Authorization
Authorization: Bearer YOUR_API_KEY

Giữ khóa trên máy chủ của bạn. Ai có khóa đều có thể tiêu Shell và Smile Coin trên tài khoản của bạn, vì vậy đừng đặt nó trong website hay ứng dụng điện thoại.

Khóa API chỉ dùng được cho các endpoint đơn hàng và vật phẩm trên trang này.

Danh sách mã vật phẩm

GET/api/items

Trả về những gì một game đang bán, đọc trực tiếp qua tài khoản mặc định của bạn, kèm mã vật phẩm để gửi trong đơn.

TrườngGhi chú
gamequery · Bắt buộcGame: freefire, mobilelegends, magicchessgogo hoặc bloodstrike.
regionquery · Không bắt buộcChỉ cho Free Fire, và bắt buộc ở đó: KH, MY, SG, PH, VN hoặc TW.
GameGhi chú
freefireFree Fire. Mã vật phẩm của nó mang khu vực cửa hàng: freefire-KH-100.
mobilelegendsMobile Legends. Gửi serverId (Zone ID) cùng đơn.
magicchessgogoMagic Chess: Go Go. Gửi serverId cùng đơn.
bloodstrikeBlood Strike. Không có serverId và region.
Ví dụ yêu cầu
curl "https://topupkit.com/api/items?game=freefire&region=KH" \
  -H "Authorization: Bearer YOUR_API_KEY"
Ví dụ phản hồi
{
  "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
    }
  ]
}

Đặt đơn

POST/api/orders

Nhận đơn hàng và trả lời ngay với status pending. Sau đó việc thanh toán chạy ở chế độ nền, thường dưới một phút và lâu nhất khoảng ba phút. Lấy kết quả bằng cách đọc đơn hàng hoặc qua callback. Đơn bị từ chối vẫn là đơn hàng, có kèm lý do.

Yêu cầu

TrườngGhi chú
Authorizationheader · Bắt buộcBearer, rồi đến khóa API của bạn.
Idempotency-Keyheader · Không bắt buộcTên duy nhất do bạn đặt cho đơn này, tối đa 255 ký tự. Rất nên dùng.
itemstring · Bắt buộcMã vật phẩm từ danh sách vật phẩm: freefire-KH-100 cho Free Fire, mang khu vực cửa hàng trong mã, hoặc mobilelegends-22590. Nó cho biết đơn dành cho game nào.
playerIdstring · Bắt buộcNgười chơi nhận vật phẩm. Chỉ gồm chữ số, tối đa 20.
serverIdstring · Không bắt buộcChỉ cho game có yêu cầu: Zone ID của Mobile Legends hoặc Server ID của Magic Chess: Go Go. Nếu không thì bỏ trống.
accountIdstring · Không bắt buộcKhông bắt buộc. Tài khoản nhà cung cấp thanh toán. Nếu không có, tài khoản mặc định của bạn cho nhà cung cấp đó (và khu vực, với Free Fire) sẽ thanh toán.
Ví dụ yêu cầu
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"
  }'
Ví dụ body cho Mobile Legends
{
  "item": "mobilelegends-22590",
  "playerId": "123456789",
  "serverId": "2001"
}

201 với đơn mới. 200 khi Idempotency-Key này đã được dùng: bạn nhận lại đơn đầu tiên và không phải trả thêm.

Ví dụ phản hồi
{
  "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
  }
}

Đối tượng đơn hàng

TrườngGhi chú
idstringID của đơn, để đọc lại sau.
supplierstringAi xử lý đơn: garena hoặc smileone.
gamestringGame: freefire, mobilelegends, magicchessgogo hoặc bloodstrike.
itemstringMã vật phẩm từ danh sách vật phẩm: freefire-KH-100 cho Free Fire, mang khu vực cửa hàng trong mã, hoặc mobilelegends-22590. Nó cho biết đơn dành cho game nào.
regionstring | nullKhu vực cửa hàng Free Fire. Null với game khác.
serverIdstring | nullServer ID đã gửi cùng đơn. Null khi game không có.
playerIdstringNgười chơi nhận vật phẩm. Chỉ gồm chữ số, tối đa 20.
statusstringXem Trạng thái đơn hàng.
playerNicknamestring | nullTên người chơi, khi nhà cung cấp đã cho biết.
itemNamestring | nullTên vật phẩm theo nhà cung cấp. Null với Free Fire.
pricestring | nullSố Garena đã hoặc sẽ thu, dạng chữ, như 13 Shell. Null với game khác.
providerReferencestring | nullMã giao dịch của nhà cung cấp, khi có.
supplierMessagestring | nullLời của nhà cung cấp khi từ chối đơn.
failureReasonstring | nullLý do đơn thất bại. Chỉ có khi status là failed.
createdAtstringThời điểm tạo đơn (ngày ISO).
settledAtstring | nullThời điểm lưu câu trả lời của nhà cung cấp (ISO date). Null khi đang pending.

Trạng thái đơn hàng

Trạng tháiÝ nghĩa
successNhà cung cấp đã nhận đơn và trừ Shell hoặc Smile Coin.
failedNhà cung cấp không trừ gì. failureReason cho biết lý do.
unknownCâu trả lời bị mất, nên Shell hoặc Smile Coin có thể đã bị trừ hoặc chưa. Kiểm tra lịch sử tài khoản trước khi đặt lại.
pendingĐã nhận và đang thanh toán. Hãy đọc lại đơn hàng hoặc chờ callback. Sau 10 phút, đơn chuyển thành unknown.

Lý do thất bại

Có trên đơn thất bại. Trong mọi trường hợp nhà cung cấp không trừ gì.

MãÝ nghĩa
player_not_foundGarena không biết ID người chơi này. Không có Shell nào bị trừ.
player_region_not_allowedCửa hàng này không bán được cho khu vực của người chơi. Không có Shell nào bị trừ.
item_not_availableVật phẩm này hiện không có cho người chơi này. Không có Shell nào bị trừ.
insufficient_shellTài khoản Garena này không đủ Shell. Không có Shell nào bị trừ.
otp_rejectedGarena không chấp nhận mã xác thực. Kiểm tra mã bí mật xác thực của tài khoản. Không có Shell nào bị trừ.
garena_refusedGarena từ chối đơn này. Không có Shell nào bị trừ.
garena_unavailableKhông kết nối được Garena. Hãy thử lại sau một lát. Không có Shell nào bị trừ.
smileone_account_expiredCookie của tài khoản không còn hoạt động. Hãy dán cookie mới. Không có khoản nào bị trừ.
smileone_refusedSmileOne từ chối đơn hàng này. Không có khoản nào bị trừ.
smileone_unavailableKhông thể kết nối tới SmileOne. Không có khoản nào bị trừ.

Đọc một đơn

GET/api/orders/{id}

Trả về đơn hàng có ID này. Hãy hỏi vài giây một lần cho đến khi status không còn là pending.

Danh sách đơn gần đây

GET/api/orders

Trả về 20 đơn hàng mới nhất của bạn, đặt bằng API key hoặc trên trang. Thêm ?supplier=garena hoặc ?supplier=smileone để lấy một nhà cung cấp.

Callback

Callback (còn gọi là webhook) là yêu cầu chúng tôi gửi đến máy chủ của bạn khi đơn đặt bằng khóa API của bạn hoàn tất, nên bạn không cần hỏi liên tục. Nó dùng cùng đối tượng đơn hàng, và chỉ đến khi status là success, failed hoặc unknown. Đọc đơn hàng vẫn luôn dùng được.

Trên trang khóa API, nhấn Callback trên khóa của bạn và nhập địa chỉ https://. Bạn nhận khóa ký một lần duy nhất. Nhấn Gửi thử để kiểm tra máy chủ: bản thử có header X-Callback-Event: test và một đơn hàng mẫu.

Máy chủ của bạn nhận được gì
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"
}

Hãy kiểm tra chữ ký trước khi tin một callback. Đó là HMAC-SHA256 của timestamp, một dấu chấm và body chính xác, dùng khóa ký của bạn.

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;

Ai tìm được địa chỉ của bạn cũng có thể gửi “success” giả. Nếu không kiểm tra, họ có thể nhận vật phẩm miễn phí.

Hãy trả lời trạng thái 2xx trong vòng 10 giây. Mọi câu trả lời khác sẽ được thử lại, tối đa năm lần nữa trong khoảng sáu giờ. Bạn có thể nhận cùng một đơn hai lần, nên hãy dùng id của đơn để bỏ qua bản lặp. Chúng tôi không đi theo chuyển hướng, và địa chỉ trên mạng riêng bị từ chối.

Thử lại an toàn

Nếu yêu cầu hết thời gian chờ, bạn không biết đơn đã trả hay chưa. Gửi lại với cùng Idempotency-Key: đơn đầu tiên được trả về và không bị trả hai lần. Không có header này, mỗi yêu cầu là một đơn mới và có thể trả thêm.

Định dạng phản hồi

Mọi phản hồi đều là JSON có trường ok. Khi ok là true, kết quả nằm trong data. Khi là false, hãy dựa vào error.code: error.message có thể thay đổi.

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

Lỗi

Đơn bị từ chối không phải là lỗi: nó trả về với status failed. Các mã này nghĩa là không xử lý được chính yêu cầu đó.

MãÝ nghĩa
400INVALID_JSONCó lỗi khi gửi nội dung này. Hãy tải lại trang và thử lại.
400VALIDATION_ERRORMột trường bị thiếu hoặc sai. error.message nêu vấn đề.
401UNAUTHORIZEDKhóa API bị thiếu, sai hoặc đã xóa.
404NOT_FOUNDĐơn này không tồn tại, hoặc không phải của bạn.
409NO_DEFAULT_ACCOUNTChưa chọn tài khoản trả tiền cho đơn API của game này. Mở trang Garena hoặc SmileOne và nhấn “Dùng cho đơn API” trên một tài khoản.
409GARENA_ACCOUNT_NOT_READY_FOR_ORDERSTài khoản Garena này chưa được cài đặt để đặt hàng. Hãy nhập UID và mã bí mật xác thực trước.
413PAYLOAD_TOO_LARGENội dung quá lớn để gửi. Hãy rút ngắn ghi chú hoặc các ô dài khác rồi thử lại.
500INTERNAL_ERRORCó lỗi ở phía chúng tôi. Thử lại sau một lát.