API đại lý: đặt voucher MB từ hệ thống của bạn
Voucher là mã ưu đãi dùng trong ứng dụng ngân hàng theo thể lệ — không phải tiền mặt, không quy đổi thành tiền.
VMB Shop là đơn vị bán lại độc lập, không phải MB Bank và không liên kết chính thức với Ngân hàng TMCP Quân đội (MB Bank).
Bạn có web bán hàng, bot hay phần mềm riêng? API cho phép tạo đơn voucher tại VMB Shop tự động: lấy giá, tạo đơn, nhận thông tin chuyển khoản kèm mã QR và biết khi nào đơn đã thanh toán, đã giao. Giá, cách thanh toán và cách giao giống hệt khi đặt trên web.
Tóm tắt
- Địa chỉ gốc:
https://vouchermb.com/api/v1— mọi yêu cầu gửi kèmAuthorization: Bearer vmb_live_…. - Đặc tả đầy đủ (OpenAPI 3.1, nhập vào Postman/Insomnia được): /api/v1/openapi.json.
- Thanh toán: bạn (hoặc khách của bạn) chuyển khoản đúng số tiền và nội dung trả về trong đơn. Hệ thống tự ghi nhận khi tiền về; chuyển thiếu thì đơn chờ bù.
- Giao hàng: thủ công, shop gửi tặng voucher vào app MB Bank của số điện thoại đã khai báo, trong giờ 8:00–22:00. Không có mã voucher trả qua API — voucher nằm sẵn trong app của người nhận.
- Hoàn tiền theo chính sách hoàn tiền (hoàn 100% nếu không giao trong 24 giờ sau khi đủ tiền).
Lấy khoá API
Khoá do shop cấp cho từng đại lý — liên hệ Telegram @bossprivatevn. Mỗi khoá có giới hạn số đơn mỗi ngày, số yêu cầu mỗi phút và có thể có ngày hết hạn. Shop cấp thêm một khoá thử (vmb_test_…): đơn tạo bằng khoá thử là đơn thử — không giao, không cần chuyển khoản — và bạn tự giả lập trạng thái để thử luồng của mình. Giữ khoá ở phía máy chủ, không đưa vào mã chạy trên trình duyệt hay ứng dụng di động.
Các điểm cuối
| Yêu cầu | Việc |
|---|---|
GET /products | Loại voucher, bậc giá theo số lượng, tình trạng hàng, giờ giao. |
POST /orders | Tạo đơn. Bắt buộc header Idempotency-Key. Trả mã đơn, số tài khoản, nội dung chuyển khoản, QR (SVG + chuỗi VietQR). |
GET /orders/{mã} | Trạng thái đơn. Chỉ khoá đã tạo đơn xem được; khoá khác nhận 404. |
GET /orders | Danh sách đơn của khoá (mới nhất trước, limit ≤ 100, trang sau bằng before_id). |
GET /me | Thông tin khoá: thử hay thật, hạn, giới hạn, số đơn hôm nay. |
POST /orders/{mã}/simulate | Chỉ khoá thử: chuyển đơn thử sang paid / delivered / cancelled / refunded. |
Trạng thái đơn
| status | Ý nghĩa |
|---|---|
pending | Chờ chuyển khoản. pay_issue = underpaid nghĩa là đã nhận một phần, chuyển bù remaining_vnd cùng nội dung. |
paid | Đã nhận đủ tiền, đang chờ shop giao. |
delivered | Đã gửi tặng voucher vào app MB Bank của số điện thoại nhận. |
refunded | Đơn đã huỷ và đã hoàn tiền. Đơn huỷ chưa hoàn có refund_pending = true. |
cancelled / expired | Đã huỷ / quá hạn chưa thanh toán (chuyển khoản muộn vẫn được ghi nhận nếu đơn chưa huỷ). |
Ví dụ
curl
# 1) Bảng giá, tồn kho, giờ giao
curl -s https://vouchermb.com/api/v1/products -H "Authorization: Bearer $VMB_KEY"
# 2) Tạo đơn (Idempotency-Key: mỗi đơn mới một giá trị; gửi lại cùng giá trị = nhận lại đúng đơn cũ)
curl -s -X POST https://vouchermb.com/api/v1/orders \
-H "Authorization: Bearer $VMB_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: don-khach-10023" \
-d '{"product_code":"mb25m","qty":10,"link_phone":"0912345678"}'
# 3) Theo dõi trạng thái
curl -s https://vouchermb.com/api/v1/orders/VMB7K3QZ2 -H "Authorization: Bearer $VMB_KEY"PHP
<?php
$key = getenv('VMB_KEY');
function vmb($method, $path, $body = null, $idem = null) {
global $key;
$h = ["Authorization: Bearer $key", "Content-Type: application/json"];
if ($idem) $h[] = "Idempotency-Key: $idem";
$ch = curl_init("https://vouchermb.com/api/v1" . $path);
curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $h,
CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 20]);
if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
$res = json_decode(curl_exec($ch), true);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($code >= 400) throw new Exception($res['error'] . ': ' . $res['message']);
return $res;
}
$r = vmb('POST', '/orders', ['product_code' => 'mb25m', 'qty' => 1, 'link_phone' => '0912345678'], 'don-' . $orderId);
echo $r['order']['code'], ' ', $r['order']['payment']['transfer_content'], ' ', $r['order']['payment']['amount_vnd'];Python
import os, requests
API = "https://vouchermb.com/api/v1"
S = requests.Session()
S.headers["Authorization"] = "Bearer " + os.environ["VMB_KEY"]
r = S.post(f"{API}/orders", json={"product_code": "mb25m", "qty": 1, "link_phone": "0912345678"},
headers={"Idempotency-Key": f"don-{order_id}"}, timeout=20)
r.raise_for_status()
o = r.json()["order"]
print(o["code"], o["payment"]["account_no"], o["payment"]["transfer_content"], o["payment"]["amount_vnd"])
open("qr.svg", "w").write(o["payment"]["qr"]["svg"]) # ảnh QR chuyển khoản
st = S.get(f"{API}/orders/{o['code']}", timeout=20).json()["order"]["status"] # pending | paid | delivered | ...Node.js (18+)
const API = 'https://vouchermb.com/api/v1';
const H = { authorization: 'Bearer ' + process.env.VMB_KEY, 'content-type': 'application/json' };
const r = await fetch(API + '/orders', {
method: 'POST',
headers: { ...H, 'idempotency-key': 'don-' + orderId },
body: JSON.stringify({ product_code: 'mb25m', qty: 1, link_phone: '0912345678' }),
});
const j = await r.json();
if (!r.ok) throw new Error(j.error + ': ' + j.message);
console.log(j.order.code, j.order.payment.transfer_content, j.order.payment.amount_vnd);Kết quả tạo đơn
{
"ok": true,
"replayed": false,
"order": {
"code": "VMB7K3QZ2",
"status": "pending",
"test": false,
"product": { "code": "mb25m", "name": "Voucher tài khoản số đẹp 25M" },
"qty": 10, "unit_price": 21500, "total_vnd": 215000,
"paid_vnd": 0, "remaining_vnd": 215000, "pay_issue": null, "refund_pending": false,
"payment": {
"bank": "ACB", "bank_bin": "970416", "account_no": "…", "account_name": "…",
"amount_vnd": 215000, "transfer_content": "CHUYEN TIEN VMB7K3QZ2",
"qr": { "payload": "000201010212…", "svg": "<svg …>" }
},
"delivery": { "method": "mb_app_gift", "phone_mask": "09******78", "delivered_at": null },
"created_at": 1795000000000, "expires_at": 1795086400000, "paid_at": null
}
}Webhook
Nếu đăng ký URL webhook (https) với shop, mỗi khi đơn đổi trạng thái hệ thống gửi POST JSON tới URL đó trong khoảng 1 phút, kèm header X-VMB-Signature: t=<giây>,v1=<hex> — trong đó v1 = HMAC-SHA256(bí mật webhook, t + "." + body). Trả mã 2xx để xác nhận; lỗi hoặc quá 8 giây thì gửi lại sau 1, 5, 15, 60, 180, 360 phút. Có thể nhận trùng — khử trùng bằng trường id, và khi cần chắc chắn hãy đọc lại GET /orders/{mã}.
// Node — kiểm chữ ký webhook (Express: dùng body THÔ, không parse trước)
import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
if (!m) return false;
if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // chống phát lại: lệch > 5 phút
const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}
<?php // PHP
$raw = file_get_contents('php://input');
preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $_SERVER['HTTP_X_VMB_SIGNATURE'] ?? '', $m);
$ok = $m && abs(time() - (int)$m[1]) <= 300
&& hash_equals(hash_hmac('sha256', $m[1] . '.' . $raw, getenv('VMB_WEBHOOK_SECRET')), $m[2]);Lỗi và giới hạn
- Lỗi trả JSON
{"ok": false, "error": "…", "message": "…"}. Mã hay gặp:invalid_key,key_revoked,key_expired(401);bad_phone,bad_qty,bad_product(400);out_of_stock,insufficient_stock,price_changed,too_many_pending(409);rate_limited,daily_limit(429). HTTP error Ý nghĩa / cách xử lý 404 not_foundĐường dẫn API không có, hoặc mã đơn không thuộc khoá của bạn. 405 method_not_allowedSai phương thức (vd DELETE). Header Allowvà trườngallowliệt kê phương thức đúng.409 nonce_conflictIdempotency-Keyđã dùng cho đơn có nội dung khác. Đơn mới phải dùng khoá mới; gửi lại đơn cũ phải giữ nguyên nội dung.413 payload_too_largeThân yêu cầu quá lớn (tối đa 4 KB) — kiểm lại JSON gửi lên. 429 rate_limitedGọi quá nhanh (giới hạn theo khoá/phút hoặc theo IP). Chờ rồi thử lại, tôn trọng Retry-Afternếu có.502 / 504 upstreamHệ thống tạm gián đoạn. Thử lại sau ít giây (POST /orders gửi lại cùng Idempotency-Keyđể không tạo trùng).- Mỗi số điện thoại nhận tối đa 3 đơn chờ thanh toán cùng lúc. Đơn chưa thanh toán tự hết hạn sau 24 giờ.
- Gửi
expected_total(tổng bạn tính theo bảng giá) để chắc chắn không mua lệch giá: giá vừa đổi thì nhận 409price_changedvà không có đơn nào được tạo. - Mọi yêu cầu được ghi nhật ký (địa chỉ IP, đường dẫn, kết quả) để hỗ trợ và chống lạm dụng; nhật ký xoá sau 30 ngày.