Tích hợp theo dõi biến động số dư VPBank vào hệ thống của bạn.
https://bank.pai.vn/api
X-Api-Key: rbk_xxx
Mọi request đều cần API key. Tạo key tại trang API Keys & Webhooks sau khi đăng ký.
X-Api-Key: rbk_xxxxxxxxxxxxxxxx
GET /api/transactions?api_key=rbk_xxxxxxxxxxxxxxxx
Trả về danh sách giao dịch của tất cả tài khoản VPBank đang theo dõi. Tiêu thụ quota.
| Param | Kiểu | Mô tả |
|---|---|---|
bank | string | Số tài khoản ngân hàng hoặc 4 số cuối |
since | datetime | Lấy từ thời điểm này — dùng next_since từ response trước |
limit | number | Số lượng trả về (mặc định 50, tối đa 200) |
to | datetime | Đến thời điểm này (ISO 8601) |
account_id | number | Thay thế cho bank nếu biết ID nội bộ |
curl -H "X-Api-Key: rbk_xxx" \ "https://bank.pai.vn/api/transactions?bank=0123456789&since=2026-06-12T00:00:00"
{
"success": true,
"count": 1,
"next_since": "2026-06-12T10:30:00.000Z",
"data": [{
"id": 42,
"tx_id": "a1b2c3d4...",
"account_number": "0123456789",
"account_label": "Tài khoản chính",
"amount": 100000,
"balance": 5000000,
"description": "CK MADON123 tu Nguyen Van A",
"tx_date": "2026-06-12T10:30:00.000Z"
}]
}
next_since từ response, dùng làm since cho lần gọi tiếp theo — chỉ nhận giao dịch mới, không bao giờ trùng.
Trả về giao dịch gần nhất của từng tài khoản. Dùng để hiển thị số dư hiện tại. Không tiêu thụ quota.
curl -H "X-Api-Key: rbk_xxx" "https://bank.pai.vn/api/transactions/latest"
{
"success": true,
"data": [{
"account_id": 1,
"account_label": "Tài khoản chính",
"amount": 50000,
"balance": 5000000,
"tx_date": "2026-06-12T10:30:00.000Z"
}]
}
Kiểm tra có giao dịch nào khớp số tiền + nội dung không. Dùng cho xác nhận thanh toán on-demand.
| Param | Bắt buộc | Mô tả |
|---|---|---|
account_id | ✓ | ID tài khoản VPBank |
amount | ✓ | Số tiền chính xác (VND, số nguyên, VD: 100000) |
keyword | — | Từ khóa trong nội dung chuyển khoản |
since | — | Chỉ tìm từ thời điểm này (khuyên dùng để tránh nhầm giao dịch cũ) |
curl -H "X-Api-Key: rbk_xxx" \ "https://bank.pai.vn/api/transactions/check?account_id=1&amount=100000&keyword=ORDER123&since=2026-06-12T10:00:00"
{
"success": true,
"found": true,
"data": [{
"id": 42,
"amount": 100000,
"description": "CK ORDER123 tu 0987654321",
"tx_date": "2026-06-12T10:30:00.000Z"
}]
}
since bằng thời điểm tạo đơn hàng để tránh nhận nhầm giao dịch cũ cùng số tiền.
Server-Sent Events — giữ kết nối liên tục, nhận thông báo ngay khi có giao dịch mới. Xác thực qua query param ?token= (JWT token, lấy sau khi đăng nhập).
const es = new EventSource('/api/transactions/sse?token=YOUR_JWT_TOKEN');
es.onmessage = (e) => {
const tx = JSON.parse(e.data);
console.log('Giao dịch mới:', tx.amount, tx.description);
};
es.onerror = () => {
// Tự reconnect sau 5 giây
setTimeout(() => initSSE(), 5000);
};
: keepalive mỗi 30 giây để giữ kết nối. SSE phù hợp cho dashboard web — dùng Webhook cho backend tích hợp.
Khi có giao dịch mới, hệ thống POST payload đến URL bạn đăng ký. Retry tối đa 3 lần với exponential backoff. Cần gói Basic trở lên.
{
"event": "new_transaction",
"tx_id": "a1b2c3d4...",
"account_id": 1,
"account_label": "Tài khoản chính",
"amount": 100000,
"balance": 5000000,
"description": "CK ORDER123 tu Nguyen Van A",
"tx_date": "2026-06-12T10:30:00.000Z"
}
const crypto = require('crypto');
app.post('/webhook', (req, res) => {
const sig = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(JSON.stringify(req.body))
.digest('hex');
if (`sha256=${sig}` !== req.headers['x-regx-signature']) {
return res.status(401).send('Invalid signature');
}
// Xử lý giao dịch
const { amount, description } = req.body;
console.log('Nhận tiền:', amount, description);
res.sendStatus(200);
});
2xx để xác nhận đã nhận. Nếu server trả lỗi hoặc timeout, hệ thống sẽ retry sau 10s, 30s, 60s.
| HTTP | Ý nghĩa |
|---|---|
401 | API key không hợp lệ hoặc thiếu |
403 | Gói dịch vụ không hỗ trợ (VD: webhook cần Basic trở lên) |
404 | Tài khoản không tồn tại hoặc không thuộc về bạn |
429 | Hết quota request trong tháng |
500 | Lỗi server nội bộ |
{
"success": false,
"message": "Mô tả lỗi cụ thể"
}
Mỗi lần gọi GET /transactions hoặc GET /transactions/check tiêu thụ 1 request. Quota reset đầu mỗi tháng.