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
Xác thực
Gửi khóa API trong header Authorization của mọi yêu cầu.
Authorization: Bearer YOUR_API_KEYGiữ 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ường | Ghi chú |
|---|---|
gamequery · Bắt buộc | Game: freefire, mobilelegends, magicchessgogo hoặc bloodstrike. |
regionquery · Không bắt buộc | Chỉ cho Free Fire, và bắt buộc ở đó: KH, MY, SG, PH, VN hoặc TW. |
| Game | Ghi chú |
|---|---|
freefire | Free Fire. Mã vật phẩm của nó mang khu vực cửa hàng: freefire-KH-100. |
mobilelegends | Mobile Legends. Gửi serverId (Zone ID) cùng đơn. |
magicchessgogo | Magic Chess: Go Go. Gửi serverId cùng đơn. |
bloodstrike | Blood Strike. Không có serverId và 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
}
]
}Đặ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ường | Ghi chú |
|---|---|
Authorizationheader · Bắt buộc | Bearer, rồi đến khóa API của bạn. |
Idempotency-Keyheader · Không bắt buộc | Tê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ộc | Mã 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ộc | Người chơi nhận vật phẩm. Chỉ gồm chữ số, tối đa 20. |
serverIdstring · Không bắt buộc | Chỉ 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ộc | Khô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. |
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 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.
{
"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ường | Ghi chú |
|---|---|
idstring | ID của đơn, để đọc lại sau. |
supplierstring | Ai xử lý đơn: garena hoặc smileone. |
gamestring | Game: freefire, mobilelegends, magicchessgogo hoặc bloodstrike. |
itemstring | Mã 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 | null | Khu vực cửa hàng Free Fire. Null với game khác. |
serverIdstring | null | Server ID đã gửi cùng đơn. Null khi game không có. |
playerIdstring | Người chơi nhận vật phẩm. Chỉ gồm chữ số, tối đa 20. |
statusstring | Xem Trạng thái đơn hàng. |
playerNicknamestring | null | Tên người chơi, khi nhà cung cấp đã cho biết. |
itemNamestring | null | Tên vật phẩm theo nhà cung cấp. Null với Free Fire. |
pricestring | null | Số Garena đã hoặc sẽ thu, dạng chữ, như 13 Shell. Null với game khác. |
providerReferencestring | null | Mã giao dịch của nhà cung cấp, khi có. |
supplierMessagestring | null | Lời của nhà cung cấp khi từ chối đơn. |
failureReasonstring | null | Lý do đơn thất bại. Chỉ có khi status là failed. |
createdAtstring | Thời điểm tạo đơn (ngày ISO). |
settledAtstring | null | Thờ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 |
|---|---|
success | Nhà cung cấp đã nhận đơn và trừ Shell hoặc Smile Coin. |
failed | Nhà cung cấp không trừ gì. failureReason cho biết lý do. |
unknown | Câ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_found | Garena không biết ID người chơi này. Không có Shell nào bị trừ. |
player_region_not_allowed | Cử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_available | Vậ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_shell | Tài khoản Garena này không đủ Shell. Không có Shell nào bị trừ. |
otp_rejected | Garena 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_refused | Garena từ chối đơn này. Không có Shell nào bị trừ. |
garena_unavailable | Khô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_expired | Cookie 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_refused | SmileOne từ chối đơn hàng này. Không có khoản nào bị trừ. |
smileone_unavailable | Khô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.
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.
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.
{
"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_JSON | Có lỗi khi gửi nội dung này. Hãy tải lại trang và thử lại. |
400VALIDATION_ERROR | Một trường bị thiếu hoặc sai. error.message nêu vấn đề. |
401UNAUTHORIZED | Khó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_ACCOUNT | Chư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_ORDERS | Tà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_LARGE | Nộ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_ERROR | Có lỗi ở phía chúng tôi. Thử lại sau một lát. |