Tham số Body (JSON hoặc Form POST)
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| merchantId | string | Có | Mã định danh cửa hàng (VD: BGW_A1B2C3D4). |
| orderId | string | Có | Mã đơn hàng duy nhất (1-64 ký tự, A-Za-z0-9_.-). Gửi lại cùng orderId nhưng khác amount/URL trả 409 IDEMPOTENCY_CONFLICT. |
| amount | number | Có | Số tiền VND nguyên dương (2.000 – 500.000.000). |
| timestamp | number | Có | Unix timestamp (ms). Chênh lệch tối đa ±5 phút. |
| environment | string | Không | LIVE (mặc định, ký bằng sk_live_) hoặc SANDBOX (ký bằng sk_test_). |
| signatureVersion | string | Không | "1" (mặc định) hoặc "2" (bắt buộc khi ghi đè returnUrl/cancelUrl/webhookUrl). |
| signature | string | Có | v1: HMAC_SHA256(key, "${merchantId}|${orderId}|${amount}|${timestamp}"). v2: ký thêm environment và các URL override. |
| returnUrl / cancelUrl / webhookUrl | string | Không | Chỉ được ghi đè khi dùng signatureVersion="2" (HTTPS trong production, chống SSRF). |
Tích hợp HTML Form POST (Chuẩn SePay / 9Pay)
Ngoài REST API trả JSON, bạn có thể submit thẳng từ form HTML (ký ở server PHP/Node) tới POST /api/v1/payment-gateway/checkout/form. Hệ thống xác thực chữ ký và chuyển hướng HTTP 303 tới trang thanh toán QR.
<?php
$merchantId = getenv("BGW_MERCHANT_ID");
$secretKey = getenv("BGW_SECRET_KEY");
$orderId = "DH_" . time();
$amount = 50000;
$timestamp = round(microtime(true) * 1000);
$signature = hash_hmac("sha256", "$merchantId|$orderId|$amount|$timestamp", $secretKey);
?>
<form method="POST" action="https://api.bankgateway.org/api/v1/payment-gateway/checkout/form">
<input type="hidden" name="merchantId" value="<?= $merchantId ?>" />
<input type="hidden" name="orderId" value="<?= $orderId ?>" />
<input type="hidden" name="amount" value="<?= $amount ?>" />
<input type="hidden" name="timestamp" value="<?= $timestamp ?>" />
<input type="hidden" name="signature" value="<?= $signature ?>" />
<button type="submit">Thanh toán VietQR</button>
</form>Code mẫu REST API (Node.js / PHP / Python)
import crypto from "node:crypto";
const merchantId = process.env.BGW_MERCHANT_ID;
const secretKey = process.env.BGW_SECRET_KEY;
const orderId = "DH_10001";
const amount = 50000;
const timestamp = Date.now();
const signature = crypto
.createHmac("sha256", secretKey)
.update(`${merchantId}|${orderId}|${amount}|${timestamp}`)
.digest("hex");
const res = await fetch("https://api.bankgateway.org/api/v1/payment-gateway/checkout", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ merchantId, orderId, amount, timestamp, signature })
});
const json = await res.json();
// Redirect khách sang json.data.checkoutUrl