Tài liệu API
Polling: ● Active
...
Tài liệu API

Tích hợp theo dõi biến động số dư VPBank vào hệ thống của bạn.

BASE URL
https://bank.pai.vn/api
XÁC THỰC
X-Api-Key: rbk_xxx
Xác thực

Mọi request đều cần API key. Tạo key tại trang API Keys & Webhooks sau khi đăng ký.

Header (khuyên dùng)
X-Api-Key: rbk_xxxxxxxxxxxxxxxx
Query param (tiện cho test)
GET /api/transactions?api_key=rbk_xxxxxxxxxxxxxxxx
GET /transactions Lấy lịch sử giao dịch

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.

ParamKiểuMô tả
bankstringSố tài khoản ngân hàng hoặc 4 số cuối
sincedatetimeLấy từ thời điểm này — dùng next_since từ response trước
limitnumberSố lượng trả về (mặc định 50, tối đa 200)
todatetimeĐến thời điểm này (ISO 8601)
account_idnumberThay thế cho bank nếu biết ID nội bộ
Request
curl -H "X-Api-Key: rbk_xxx" \
  "https://bank.pai.vn/api/transactions?bank=0123456789&since=2026-06-12T00:00:00"
Response
{
  "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"
  }]
}
Pattern polling chuẩn: Lưu 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.
GET /transactions/latest Giao dịch mới nhất mỗi tài khoản

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.

Request
curl -H "X-Api-Key: rbk_xxx" "https://bank.pai.vn/api/transactions/latest"
Response
{
  "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"
  }]
}
GET /transactions/check Kiểm tra giao dịch cụ thể

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.

ParamBắt buộcMô tả
account_idID tài khoản VPBank
amountSố tiền chính xác (VND, số nguyên, VD: 100000)
keywordTừ khóa trong nội dung chuyển khoản
sinceChỉ tìm từ thời điểm này (khuyên dùng để tránh nhầm giao dịch cũ)
Request
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"
Response
{
  "success": true,
  "found": true,
  "data": [{
    "id": 42,
    "amount": 100000,
    "description": "CK ORDER123 tu 0987654321",
    "tx_date": "2026-06-12T10:30:00.000Z"
  }]
}
Luôn truyền 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.
SSE /transactions/sse Nhận giao dịch realtime

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

JavaScript
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);
};
Server gửi comment : 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.
WEBHOOK POST your-callback-url Giao dịch realtime qua callback

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.

Payload
{
  "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"
}
Xác minh chữ ký — Node.js
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);
});
Trả về HTTP 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.
Mã lỗi
HTTPÝ nghĩa
401API key không hợp lệ hoặc thiếu
403Gói dịch vụ không hỗ trợ (VD: webhook cần Basic trở lên)
404Tài khoản không tồn tại hoặc không thuộc về bạn
429Hết quota request trong tháng
500Lỗi server nội bộ
Format lỗi
{
  "success": false,
  "message": "Mô tả lỗi cụ thể"
}
Quota & Giới hạn

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.

Đang tải...
Webhook và SSE không tiêu thụ quota — server chủ động đẩy xuống, client không gọi gì.