Merchant API: POST /api/rechargews (MD5 Sign) REST API: Bearer USER_TOKEN Webhook Callback & Tự động hoàn tiền

Tài Liệu Đấu Nối API Chung Sức Liên Quân

Hỗ trợ đồng thời 2 chuẩn kết nối: Merchant API Rechargews / NapVip (/api/rechargews) ký MD5 chuẩn hóa cho các shop nạp game tự động và RESTful Bearer API (/api/v1/chungsuc/*). Tự động áp dụng chiết khấu cấp bậc & tài khoản thời gian thực.
Tải Tài Liệu Đầy Đủ (.md)
Danh mục gói Chung Sức chuẩn (service_code: chungsuc_lq)
package_codeTên góiSố lượtSố vé (tickets)Giá niêm yết (amount)
goi-381 Lượt138 vé2.000đ
goi-152Rương SS4152 vé5.000đ
goi-320Full 3 Rương9320 vé10.000đ
goi-500500 Vé14500 vé15.000đ
goi-10001000 Vé271,000 vé25.000đ
goi-50005000 Vé1325,000 vé75.000đ
goi-1000010.000 Vé26410,000 vé150.000đ
Quy tắc tạo chữ ký bảo mật MD5 (sign):
  • Với lệnh getbalance, productlist: sign = md5(partner_key + partner_id + command)
  • Với lệnh topup, topup_v2, getstatus: sign = md5(partner_key + partner_id + command + request_id)
  • Endpoint duy nhất: POST https://chungsuclq.top/api/rechargews (Body JSON hoặc x-www-form-urlencoded).
POST /api/rechargews — command: "getbalance"
Tra cứu số dư ví Merchant và phần trăm chiết khấu đang áp dụng.
{
  "partner_id": "100001",
  "command": "getbalance",
  "sign": "md5(partner_key + partner_id + 'getbalance')"
}
{
  "status": "success",
  "message": "success",
  "data": {
    "balance": 500000,
    "discount": 0,
    "currency": "VND"
  }
}
POST /api/rechargews — command: "productlist"
Lấy danh sách gói nạp chungsuc_lq kèm giá gốc (price), phần trăm giảm giá (discount) và giá thực trừ sau chiết khấu (pay_amount).
{
  "partner_id": "100001",
  "command": "productlist",
  "game_key": "chungsuc_lq",
  "sign": "md5(partner_key + partner_id + 'productlist')"
}
POST /api/rechargews — command: "topup" (hoặc "topup_v2")
Tạo đơn bơm vé Chung Sức Liên Quân tự động. Truyền mã mời hoặc nguyên văn tin nhắn chia sẻ Garena vào account (hoặc uid / event_code). Chọn gói qua package_code (khuyến nghị: goi-38 .. goi-10000), hoặc truyền mệnh giá gốc vào amount (2000, 5000, 10000, 15000, 25000, 75000, 150000), hoặc số vé lẻ vào tickets.
{
  "partner_id": "100001",
  "command": "topup",
  "request_id": "REQ_20261030_0001",
  "service_code": "chungsuc_lq",
  "package_code": "goi-152",
  "amount": 5000,
  "qty": 1,
  "account": "AbCdEf1234",
  "callback_url": "https://shopcuaban.vn/api/callback/rechargews",
  "sign": "md5(partner_key + partner_id + 'topup' + request_id)"
}
Response JSON
{
  "status": "pending",
  "message": "Đơn hàng đã được tiếp nhận và đang bơm vé tự động",
  "data": {
    "order_code": "CS-261030-A1B2C3",
    "request_id": "REQ_20261030_0001",
    "status": "pending",
    "account": "AbCdEf1234",
    "package_code": "goi-152",
    "package_name": "Rương SS",
    "qty": 1,
    "target_tickets": 152,
    "done_tickets": 0,
    "progress_percent": 0,
    "amount": 5000,
    "discount": 0,
    "pay_amount": 4500,
    "balance": 495500,
    "currency": "VND"
  }
}
POST /api/rechargews — command: "getstatus"
Kiểm tra tiến độ đơn nạp theo request_id (hoặc order_code). Trạng thái trả về chuẩn 6 giá trị: pending, processing, completed, failed, canceled, none.
{
  "partner_id": "100001",
  "command": "getstatus",
  "request_id": "REQ_20261030_0001",
  "sign": "md5(partner_key + partner_id + 'getstatus' + request_id)"
}
WEBHOOK Callback tự động khi đơn Hoàn thành / Thất bại / Hoàn tiền
Xem bảng dữ liệu Callback
Truyền callback_url trực tiếp trong lệnh topup hoặc cài mặc định tại Hồ sơ tài khoản. Chữ ký kiểm tra: callback_sign = md5(partner_key + request_id + order_code + status) (xem bảng giải thích chi tiết từng trường ở khung bên dưới).
3 cách truyền khóa xác thực USER_TOKEN cực kỳ linh hoạt:
  • Cách 1 (Khuyên dùng): Header Authorization: Bearer YOUR_USER_TOKEN
  • Cách 2: Header X-API-Key: YOUR_USER_TOKEN
  • Cách 3 (Tiện test nhanh / PHP): Truyền trực tiếp "api_key": "YOUR_USER_TOKEN" trong JSON Body hoặc Query ?api_key=YOUR_USER_TOKEN.
GET /api/v1/me (hoặc /api/v1/chungsuc/balance)
Kiểm tra số dư khả dụng (balance), cấp bậc hiện tại và phần trăm chiết khấu giảm giá (discount_percent) đang áp dụng trên tài khoản.
Response JSON
{
  "status": "success",
  "ok": true,
  "data": {
    "username": "shopgame247",
    "partner_id": "100001",
    "balance": 500000,
    "total_balance": 2000000,
    "ranks": "daily",
    "discount_percent": 0
  }
}
GET /api/v1/chungsuc/packages
Lấy danh sách gói vé đang mở bán và cấu hình vé lẻ theo thời gian thực. Nếu truyền kèm USER_TOKEN, API trả sẵn giá thực trừ sau chiết khấu (effective_price).
Response JSON
{
  "status": "success",
  "ok": true,
  "data": {
    "service_status": 1,
    "discount_percent": 0,
    "packages": [
      {
        "code": "goi-38",
        "name": "1 Lượt",
        "turns": 1,
        "tickets": 38,
        "price": 2000,
        "discount_percent": 0,
        "effective_price": 1800
      },
      {
        "code": "goi-152",
        "name": "Rương SS",
        "turns": 4,
        "tickets": 152,
        "price": 5000,
        "discount_percent": 0,
        "effective_price": 4500
      }
    ],
    "custom_ticket_config": {
      "enabled": true,
      "price_per_ticket": 50,
      "effective_price_per_ticket": 45,
      "min_tickets": 38,
      "max_tickets": 20000
    }
  }
}
POST /api/v1/chungsuc/orders (alias: /api/v1/chungsuc/create)
Tạo 1 đơn hoặc hàng loạt đơn Chung Sức cùng lúc, trừ tiền nguyên tử theo giá đã chiết khấu và đẩy thẳng sang máy chủ bơm vé. Tự động bóc mã mời sạch dù khách dán nguyên câu chia sẻ từ game Garena (VD: ... --AbCdEf1234-- ...).
Tham sốKiểuBắt buộcÝ nghĩa & Cách dùng dễ nhất
code hoặc codesstring | string[]Bắt buộcTruyền "code": "AbCdEf1234" cho 1 đơn lẻ (chấp nhận cả invite_code, event_code, account), hoặc "codes": ["Ma1", "Ma2"] để tạo nhiều đơn cùng lúc.
package_codestring1 trong 3Cách 1 (Khuyên dùng): Mã gói chuẩn trong bảng phía trên (goi-38, goi-152, goi-320, goi-500, goi-1000, goi-5000, goi-10000).
amountinteger1 trong 3Cách 2: Chọn gói theo mệnh giá gốc niêm yết (2000, 5000, 10000, 15000, 25000, 75000, 150000).
ticketsinteger1 trong 3Cách 3: Đặt số vé lẻ tùy chỉnh (VD: 200 vé), tùy chọn kèm "use_vip_pool": true.
qtyintegerTùy chọnHệ số nhân số lượng gói trên mỗi mã mời (mặc định 1, tối đa 50).
request_idstringTùy chọnMã đơn hàng bên Shop của bạn — chống tạo trùng đơn nếu gọi lại và trả nguyên vẹn về trong Webhook Callback.
callback_urlstring (URL)Tùy chọnURL nhận thông báo tự động khi đơn hoàn tất / lỗi / hoàn tiền (bỏ trống sẽ tự dùng URL cài trong Hồ sơ). Hỗ trợ thêm callback_type (POST/GET) và callback_post_type (Json/Form).
notestringTùy chọnGhi chú đơn hàng (tối đa 120 ký tự).
Mẫu 1: Gọi tối giản (1 mã mời)
{
  "package_code": "goi-152",
  "code": "AbCdEf1234"
}
Mẫu 2: Đầy đủ cho Shop tự động (kèm Callback)
{
  "package_code": "goi-152",
  "code": "AbCdEf1234",
  "request_id": "SHOP_ORDER_1001",
  "callback_url": "https://shopcuaban.vn/api/callback/chungsuc",
  "note": "Khach hang #1001"
}
Response JSON (200 OK)
{
  "status": "success",
  "ok": true,
  "msg": "Tạo thành công 1 đơn Chung Sức Liên Quân!",
  "data": {
    "idempotent_replay": false,
    "created_count": 1,
    "discount_percent": 0,
    "total_charged": 4500,
    "balance_remaining": 495500,
    "order": {
      "order_code": "CS-261030-A1B2C3",
      "request_id": "SHOP_ORDER_1001",
      "package_code": "goi-152",
      "package_name": "Rương SS",
      "event_code": "AbCdEf1234",
      "invite_code": "AbCdEf1234",
      "qty": 1,
      "target_tickets": 152,
      "done_tickets": 0,
      "remain_tickets": 152,
      "progress_percent": 0,
      "unit_price": 5000,
      "discount_percent": 0,
      "total_price": 4500,
      "pay_amount": 4500,
      "status": "pending",
      "callback_url": "https://shopcuaban.vn/api/callback/chungsuc",
      "created_at": "2026-10-30T12:00:00.000Z"
    },
    "orders": [ /* Danh sách toàn bộ đơn được tạo trong lần gọi này */ ]
  }
}
GET /api/v1/chungsuc/orders/:orderCode (nhận cả order_code lẫn request_id)
Tra cứu tiến độ vé thực tế thời gian thực theo order_code (VD: CS-261030-A1B2C3) hoặc chính request_id của shop bạn (VD: SHOP_ORDER_1001), hoặc gọi GET /api/v1/chungsuc/status?request_id=SHOP_ORDER_1001. Để lấy danh sách nhiều đơn phân trang: GET /api/v1/chungsuc/orders?page=1&limit=20&status=running.
Trạng thái (status)Trạng thái CallbackÝ nghĩa
pending—Đơn vừa khởi tạo, đang xếp hàng chuẩn bị bơm vé.
running—Đang bơm vé tự động (cập nhật done_tickets mỗi 5 giây).
completedcompletedĐã bơm đủ 100% số vé mục tiêu — bắn Callback thành công.
failedfailedĐơn dừng giữa chừng / thiếu vé (phần vé thiếu được hoàn tiền vào refund_amount) — bắn Callback.
refunded / cancelledcanceledMã mời sai/hết lượt hoặc khách hủy đơn chờ, đã hoàn tiền 100% — bắn Callback.
Response JSON
{
  "status": "success",
  "ok": true,
  "data": {
    "order_code": "CS-261030-A1B2C3",
    "request_id": "SHOP_ORDER_1001",
    "package_code": "goi-152",
    "package_name": "Rương SS",
    "event_code": "AbCdEf1234",
    "target_tickets": 152,
    "done_tickets": 152,
    "remain_tickets": 0,
    "progress_percent": 100,
    "unit_price": 5000,
    "discount_percent": 10,
    "total_price": 4500,
    "pay_amount": 4500,
    "refunded": false,
    "refund_amount": 0,
    "status": "completed",
    "callback_status": 200,
    "callback_attempts": 1,
    "logs": ["[19:01:12] ✓ acc*** -> +152 vé (152/152 vé)"]
  }
}
POST /api/v1/chungsuc/orders/:orderCode/cancel (hoặc POST /api/v1/chungsuc/cancel)
Hủy đơn đang chờ (chưa phát sinh vé done_tickets = 0) và hoàn lại 100% số tiền đã trừ vào ví ngay lập tức, đồng thời bắn Webhook Callback trạng thái canceled.
{
  "status": "success",
  "ok": true,
  "msg": "Hủy đơn và hoàn tiền thành công!",
  "data": {
    "order": {
      "order_code": "CS-261030-A1B2C3",
      "status": "cancelled",
      "refunded": true,
      "refund_amount": 4500
    },
    "balance_remaining": 500000
  }
}
WEBHOOK Đơn tạo qua REST API v1 cũng tự động bắn Webhook Callback giống hệt cổng Merchant! Xem đầy đủ bảng 19 trường dữ liệu và code mẫu nhận Callback ngay bên dưới.
Xem bảng Callback
Đặc Tả Dữ Liệu Webhook Callback (Dùng chung cả 2 cổng API)
Tự động gọi về server đối tác ngay khi đơn kết thúc — hỗ trợ POST Json (mặc định), POST Form (x-www-form-urlencoded) và GET.
Cài đặt URL Callback mặc định
Cơ chế gửi, Retry & Xác thực chữ ký chống giả mạo:
  • Thời điểm bắn Callback: Tự động kích hoạt khi đơn chuyển sang 1 trong 3 trạng thái kết thúc: completed (hoàn thành đủ vé), failed (lỗi / hoàn tiền phần vé thiếu), hoặc canceled (mã lỗi / hủy đơn hoàn tiền 100%).
  • Headers đi kèm: X-Rechargews-Event: order_callback và X-Rechargews-Sign: <callback_sign>.
  • Công thức kiểm tra chữ ký MD5: callback_sign = md5(partner_key + request_id + order_code + status) — trong đó partner_key lấy ở cột bên phải; nếu lúc tạo đơn không truyền request_id thì request_id chính bằng order_code.
  • Quy tắc phản hồi & Retry: Server của bạn chỉ cần trả HTTP Status 200 (hoặc 201 / 204). Nếu timeout hoặc trả mã lỗi khác, hệ thống tự động gửi lại tối đa 3 lần và lưu lịch sử đối soát.
1. Bảng giải thích đầy đủ các trường dữ liệu Callback bắn về
Tên trườngKiểuÝ nghĩa chi tiết & Giá trị mẫu
statusstringTrạng thái kết thúc chuẩn của đơn: "completed" (đủ vé), "failed" (thiếu vé / lỗi một phần) hoặc "canceled" (đã hủy / hoàn tiền 100%).
messagestringMô tả kết quả tiếng Việt rõ ràng (VD: "Hoàn thành 152/152 vé Chung Sức" hoặc lý do lỗi/hoàn tiền).
request_idstringMã tham chiếu đơn hàng bên Shop của đối tác gửi lên lúc tạo đơn (nếu không truyền sẽ bằng order_code).
order_codestringMã đơn hàng duy nhất trên hệ thống (VD: "CS-261030-A1B2C3").
callback_signstring (MD5)Chữ ký bảo mật 32 ký tự hex: md5(partner_key + request_id + order_code + status).
service_codestringMã dịch vụ ("chungsuc" / "chungsuc_lq").
accountobjectChứa mã mời sự kiện Garena: {"game_id": "AbCdEf1234", "invite_code": "AbCdEf1234"} (với POST Form / GET sẽ truyền thêm account[game_id]).
package_code / package_namestringMã gói và tên gói đã chạy (VD: "goi-152" / "Rương SS" hoặc "custom").
target_ticketsintegerTổng số vé mục tiêu cần bơm của đơn (VD: 152).
done_tickets / remain_ticketsintegerSố vé thực tế đã bơm thành công và số vé còn thiếu (khi completed thì remain_tickets = 0).
amount / request_valueintegerMệnh giá niêm yết gốc của đơn trước chiết khấu (VD: 5000).
complete_value / remain_valueintegerGiá trị mệnh giá tương ứng phần vé đã hoàn thành và phần còn lại (chuẩn đối soát Rechargews).
discountnumberPhần trăm chiết khấu giảm giá đã áp dụng cho đơn (0 đến 100).
pay_amountintegerSố tiền thực tế đã trừ ví của đối tác sau chiết khấu (VD: 4500).
refunded / refund_amountboolean / intĐánh dấu đơn đã được tự động hoàn tiền hay chưa (true/false) và số tiền (VNĐ) đã cộng hoàn lại vào ví đối tác.
timestringThời gian tạo đơn theo giờ Việt Nam (YYYY-MM-DD HH:mm:ss).
2A. JSON Callback khi Đơn Hoàn Thành (completed)
{
  "status": "completed",
  "message": "Hoàn thành 152/152 vé Chung Sức",
  "time": "2026-10-30 19:05:10",
  "request_id": "SHOP_ORDER_1001",
  "order_code": "CS-261030-A1B2C3",
  "service_code": "chungsuc",
  "account": {
    "game_id": "AbCdEf1234",
    "invite_code": "AbCdEf1234"
  },
  "package_code": "goi-152",
  "package_name": "Rương SS",
  "target_tickets": 152,
  "done_tickets": 152,
  "remain_tickets": 0,
  "amount": 5000,
  "request_value": 5000,
  "complete_value": 5000,
  "remain_value": 0,
  "discount": 10,
  "pay_amount": 4500,
  "refunded": false,
  "refund_amount": 0,
  "callback_sign": "8f14e45fceea167a5a36dedd4bea2543"
}
2B. JSON Callback khi Lỗi / Tự Hoàn Tiền (canceled)
{
  "status": "canceled",
  "message": "Mã mời sự kiện không tồn tại hoặc đã đủ lượt",
  "time": "2026-10-30 19:06:02",
  "request_id": "SHOP_ORDER_1002",
  "order_code": "CS-261030-D4E5F6",
  "service_code": "chungsuc",
  "account": {
    "game_id": "SaiMa12345",
    "invite_code": "SaiMa12345"
  },
  "package_code": "goi-152",
  "package_name": "Rương SS",
  "target_tickets": 152,
  "done_tickets": 0,
  "remain_tickets": 152,
  "amount": 5000,
  "request_value": 5000,
  "complete_value": 0,
  "remain_value": 5000,
  "discount": 10,
  "pay_amount": 4500,
  "refunded": true,
  "refund_amount": 4500,
  "callback_sign": "c9f0f895fb98ab9159f51fd0297e236d"
}
3. Code mẫu nhận & kiểm tra chữ ký Webhook Callback (Copy chạy ngay)
PHP (Shop nạp game phổ biến)
<?php
$partnerKey = 'YOUR_PARTNER_KEY';
$body = json_decode(file_get_contents('php://input'), true) ?: $_POST;

$requestId = (string)($body['request_id'] ?? '');
$orderCode = (string)($body['order_code'] ?? '');
$status    = (string)($body['status'] ?? '');
$sign      = (string)($body['callback_sign'] ?? '');

$mySign = md5($partnerKey . $requestId . $orderCode . $status);
if (!hash_equals($mySign, $sign)) {
    http_response_code(403);
    exit('Invalid signature');
}

if ($status === 'completed') {
    // Cập nhật đơn $requestId thành công
} elseif ($status === 'canceled' || $status === 'failed') {
    // Hoàn tiền cho khách (dựa theo $body['done_tickets'] / $body['refund_amount'])
}
http_response_code(200);
echo json_encode(['status' => 'ok']);
Node.js (Express)
const crypto = require('crypto');

app.post('/api/callback/chungsuc', express.json(), (req, res) => {
  const { request_id = '', order_code = '', status = '', callback_sign = '' } = req.body || {};
  const expected = crypto
    .createHash('md5')
    .update(`${process.env.PARTNER_KEY}${request_id}${order_code}${status}`, 'utf8')
    .digest('hex');

  if (expected !== String(callback_sign).toLowerCase()) {
    return res.status(403).json({ error: 'Invalid callback_sign' });
  }

  // Xử lý cập nhật trạng thái đơn theo request_id (completed / failed / canceled)
  return res.status(200).json({ status: 'ok' });
});
Merchant Rechargews
Cài Webhook
Bảng mã lỗi chuẩn Rechargews
MãÝ nghĩa
100Đơn hàng không tồn tại
101Partner ID không tồn tại / chưa kích hoạt
102Số dư ví Merchant không đủ
103Sai chữ ký MD5 sign hoặc sai JSON
104Thiếu tham số hoặc mã gói/mã mời sai
105Tài khoản bị khóa hoặc khác IP Whitelist
106Dịch vụ hoặc gói nạp đang bảo trì
107Lỗi khởi tạo đơn upstream (đã hoàn tiền)
117Lệnh command không hỗ trợ
120Lỗi ngoại lệ hệ thống (Exception)
126Số lượng qty không hợp lệ (≤ 0)