Xác thực
API dùng Token riêng của từng tài khoản ngân hàng đã liên kết (lấy trong Dashboard › Cổng thanh toán), không dùng X-API-Key.
| Header | Bắt buộc | Mô tả |
|---|---|---|
| Authorization | Bắt buộc* | Bearer YOUR_NODE_TOKEN |
| X-Token | Thay thế | Có thể dùng thay cho Authorization. |
| X-Request-Id | Tuỳ chọn | Mã truy vết; nếu bỏ trống hệ thống tự sinh và trả về trong header phản hồi. |
Tham số
| Query | Bắt buộc | Mô tả |
|---|---|---|
| accountNumber | Bắt buộc | Số tài khoản đã liên kết trên hệ thống. |
| limit | Tuỳ chọn | Số giao dịch trả về, 1–500. Mặc định 50. |
| sync | Tuỳ chọn | true để kích hoạt đồng bộ ngầm với ngân hàng (tối đa 1 lần / 10 giây / tài khoản). |
curl -X GET 'https://api.bankgateway.org/api/v1/gateway/mbbank/history?accountNumber=0783825888&limit=50' \
-H 'Authorization: Bearer YOUR_NODE_TOKEN'Phản hồi
{
"status": "success",
"requestId": "obg_3f9a1c2b7d4e",
"message": "Thành công",
"transactions": [
{
"transactionID": "FT26325123456789",
"amount": 150000,
"currency": "VND",
"balanceAfter": 2350000,
"description": "DH10293 thanh toan don hang",
"transactionDate": "21/11/2026",
"bookingDateTime": "2026-11-21T09:15:42+07:00",
"type": "IN",
"creditDebitIndicator": "CRDT",
"bankCode": "MB",
"counterPartyAccount": "0123456789",
"counterPartyName": "NGUYEN VAN A"
}
]
}| Trường | Kiểu | Mô tả |
|---|---|---|
| transactionID | string | Mã tham chiếu giao dịch phía ngân hàng. |
| amount | number | Số tiền (VND). |
| balanceAfter | number | Số dư sau giao dịch. |
| description | string | Nội dung chuyển khoản — dùng để khớp mã đơn. |
| transactionDate | string | Ngày giao dịch, định dạng dd/MM/yyyy. |
| bookingDateTime | string | Thời điểm ghi sổ ISO 8601 (+07:00). |
| type | IN | OUT | Chiều giao dịch. |
| creditDebitIndicator | CRDT | DBIT | Ghi có / ghi nợ. |
| bankCode | string | MB hoặc TCB. |
| counterPartyAccount | string | null | Tài khoản đối ứng (nếu ngân hàng cung cấp). |
| counterPartyName | string | null | Tên đối ứng (nếu ngân hàng cung cấp). |
Mã lỗi & giới hạn
| HTTP | Mã | Ý nghĩa |
|---|---|---|
| 400 | — | Thiếu số tài khoản hoặc token. |
| 401 | — | Số tài khoản hoặc token không đúng. |
| 429 | RATE_LIMIT_EXCEEDED | Quá 30 request / phút / IP. Xem header Retry-After. |
| 429 | TOKEN_BRUTEFORCE_LOCKED | Sai token quá 10 lần trong 15 phút — IP bị khóa 15 phút. |
Đường dẫn tương thích
| Endpoint | Ghi chú |
|---|---|
| GET /api/v1/gateway/mbbank/history | Khuyến nghị cho MBBank. |
| GET /api/v1/gateway/history | Dùng chung cho mọi ngân hàng đã liên kết. |
| GET /api/v1/gateway/mbbank/history/:accountNumber/:token | Cũ — token trên path. |
| GET /api/v1/historyapimbv3/:password/:accountNumber/:token | Tương thích hệ thống tích hợp cũ. |