Tích hợp BigPay
BigPay đẩy biến động số dư tới hệ thống của bạn qua webhook — POST JSON có chữ ký HMAC. Dưới đây là hợp đồng tích hợp: payload, cách xác minh chữ ký, cách phản hồi và chính sách thử lại.
Tổng quan
Khi có tiền vào/ra trên tài khoản ngân hàng đã liên kết, BigPay gửi một request POST tới URL webhook bạn cấu hình trong bảng điều khiển (mục Kênh thông báo). Hệ thống của bạn xác minh chữ ký, xử lý, rồi trả 200 kèm {"success":true}.
Xác thực
Webhook xác thực bằng chữ ký HMAC-SHA256 trên từng request (xem mục bên dưới) — bạn không cần gửi API key.
Để chủ động kéo giao dịch bằng API (REST), tạo API token trong bảng điều khiển (Cài đặt → API Access); token dạng bpk_live_… và được gửi qua header Bearer. (Pull API đang hoàn thiện — webhook là kênh tích hợp chính hiện tại.)
curl https://api.bigpay.vn/v1/transactions/list \ -H "Authorization: Bearer bpk_live_xxxxxxxx" \ -H "Content-Type: application/json"
Webhook biến động số dư
BigPay gửi tới endpoint của bạn với các header:
POST /your/webhook HTTP/1.1 Content-Type: application/json X-BigPay-Signature: <hmac_sha256_hex_của_raw_body> X-BigPay-Idempotency-Key: <id_giao_dịch>
Thân (body) là JSON:
{
"id": "SEVQR_1730000000001", // mã giao dịch (= sepay_txn_id), dùng chống trùng
"gateway": "MB", // mã ngân hàng/cổng
"transferType": "credit", // "credit" (tiền vào) | "debit" (tiền ra)
"amount": 1345000, // số tiền (VND)
"content": "BIGPAY DH10293 thanh toan",
"va": null, // tài khoản ảo (nếu có)
"paymentCode": "DH10293", // mã đối soát tách từ nội dung
"referenceCode": null,
"transactionDate": "2026-10-31T03:42:00.000Z"
}Dùng id (hoặc header idempotency) để chống trùng phía bạn: BigPay có thể gửi lại khi chưa nhận được phản hồi hợp lệ.
Xác minh chữ ký HMAC
Tính HMAC-SHA256 trên raw body (nguyên văn, chưa parse) bằng secret chung, so sánh hằng thời gian với header X-BigPay-Signature.
const crypto = require('crypto');
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
const raw = req.body; // Buffer: raw body
const expected = crypto.createHmac('sha256', SECRET)
.update(raw).digest('hex');
const got = req.header('X-BigPay-Signature') || '';
const ok = got.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
if (!ok) return res.status(401).json({ success: false });
const evt = JSON.parse(raw.toString('utf8'));
// TODO: xử lý giao dịch evt.id (chống trùng), rồi:
res.json({ success: true });
});$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, $SECRET);
$got = $_SERVER['HTTP_X_BIGPAY_SIGNATURE'] ?? '';
if (!hash_equals($expected, $got)) { http_response_code(401); exit; }
$evt = json_decode($raw, true);
// xử lý $evt['id'] ...
header('Content-Type: application/json');
echo '{"success":true}';Xác nhận & thử lại
Coi là gửi THÀNH CÔNG khi endpoint trả HTTP 200/201 và body JSON {"success":true}. Thiếu một trong hai, hoặc timeout/lỗi mạng, BigPay sẽ tự thử lại theo dãy Fibonacci:
1 → 1 → 2 → 3 → 5 → 8 → 13 (tối đa 8 lần, sau đó đánh dấu "dead")
Vì có thử lại, endpoint của bạn phải idempotent: xử lý cùng id nhiều lần không được tạo hệ quả trùng.
Phong bì lỗi
API của BigPay trả lỗi theo một phong bì thống nhất; rẽ nhánh theo error.code (ổn định), không theo message.
{
"error": { "code": "VALIDATION_ERROR", "message": "…", "details": { } },
"correlationId": "…",
"timestamp": "2026-10-31T03:42:00.000Z",
"path": "/auth/login"
}| code | HTTP | Ý nghĩa |
|---|---|---|
| VALIDATION_ERROR | 400 | Dữ liệu gửi lên không hợp lệ |
| UNAUTHORIZED | 401 | Thiếu/sai xác thực (token, cookie) |
| FORBIDDEN | 403 | Không đủ quyền / chưa kích hoạt email / CSRF |
| NOT_FOUND | 404 | Không tìm thấy tài nguyên |
| CONFLICT | 409 | Trùng dữ liệu (vd email đã tồn tại) |
| RATE_LIMITED | 429 | Vượt hạn mức, thử lại sau |
| UPSTREAM_ERROR | 502 | Lỗi khi gọi hệ thống ngân hàng |
Môi trường
BigPay kết nối trực tiếp với ngân hàng (có sandbox để thử nghiệm). URL webhook của bạn do bạn tự đặt trong bảng điều khiển; nên dùng HTTPS công khai để BigPay gửi tới được.
Bắt đầu tích hợp
Tạo tài khoản, kết nối ngân hàng và cấu hình webhook đầu tiên trong vài phút.