Tham số Body (JSON)
| 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 trên hệ thống của bạn (1-64 ký tự). |
| amount | number | Có | Số tiền VND nguyên dương (2.000 – 500.000.000). |
| timestamp | number | Có | Unix timestamp tính bằng mili-giây (Date.now()). Chênh lệch tối đa ±5 phút. |
| signature | string | Có | HMAC-SHA256 hex của chuỗi "${merchantId}|${orderId}|${amount}|${timestamp}" với Secret Key. |
| description | string | Không | Mô tả đơn hàng hiển thị cho người mua. |
| returnUrl | string | Không | Ghi đè Return URL mặc định khi thanh toán thành công. |
| cancelUrl | string | Không | Ghi đè Cancel URL mặc định khi người mua bấm Hủy. |
| webhookUrl | string | Không | Ghi đè Webhook URL mặc định (chặn IP nội bộ chống SSRF). |
Code mẫu tạo đơn (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.pro/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