TÀI LIỆU API

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.)

Ví dụ gọi Pull API (roadmap)
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:

Headers
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:

Payload
{
  "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.

Node.js (Express)
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 });
});
PHP
$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:

Lịch thử lại (phút)
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.

Hình dạng lỗi
{
  "error": { "code": "VALIDATION_ERROR", "message": "…", "details": { } },
  "correlationId": "…",
  "timestamp": "2026-10-31T03:42:00.000Z",
  "path": "/auth/login"
}
codeHTTPÝ nghĩa
VALIDATION_ERROR400Dữ liệu gửi lên không hợp lệ
UNAUTHORIZED401Thiếu/sai xác thực (token, cookie)
FORBIDDEN403Không đủ quyền / chưa kích hoạt email / CSRF
NOT_FOUND404Không tìm thấy tài nguyên
CONFLICT409Trùng dữ liệu (vd email đã tồn tại)
RATE_LIMITED429Vượt hạn mức, thử lại sau
UPSTREAM_ERROR502Lỗ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.

Dùng thử miễn phí →