01. Lấy API Key
- 01Mở Cổng quản trị API
Truy cập Dashboard > Khóa API & IP Whitelist để lấy API Key (tiền tố bg_live_...).
- 02Cấu hình IP Whitelist (Khuyến nghị)
Thêm địa chỉ IP máy chủ của bạn để kích hoạt cơ chế phòng vệ Zero-Trust.
- 03Lưu vào biến môi trường
Đặt BANKGATEWAY_API_KEY trong file .env trên máy chủ. Không lưu vào Git repository.
02. Thực hiện lệnh gọi API
# Gọi trực tiếp từ máy chủ backend (Server-to-Server).
# Bảo mật: Không bao giờ nhúng API Key vào client/web frontend.
curl -X POST 'https://api.bankgateway.pro/api/v1/lookup' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Idempotency-Key: op_$(date +%s)_$RANDOM' \
-d '{
"bankCode": "MB",
"accountNumber": "0783825888"
}'03. Cấu trúc phản hồi
Dưới đây là mẫu JSON trả về khi tìm thấy tài khoản (HTTP 200) và khi không tìm thấy tài khoản (HTTP 404):
{
"success": true,
"data": {
"requestId": "REQ_20261017_9921FA80",
"bankCode": "MB",
"bankName": "MBBank (Ngân hàng Quân Đội)",
"accountNumber": "0783825888",
"accountName": "TRAN NHU KHANG",
"cached": true,
"source": "L1_CACHE",
"verifiedAt": "2026-10-17T09:30:00.000Z",
"feeChargedVnd": 0,
"chargeMethod": "SUBSCRIPTION_PASS",
"quotaRemaining": {
"subscriptionQuota": 49850,
"vaultQuota": 0,
"walletBalanceVnd": 1500000
},
"latencyMs": 1,
"signature": "ed25519:v1:e8f90c33a91b452d88fa7b89c02d...",
"message": "Xác thực tài khoản Napas 24/7 thành công"
}
}{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Không tìm thấy thông tin tài khoản thụ hưởng tại ngân hàng đích",
"requestId": "REQ_20261017_9921FA81",
"bankCode": "MB",
"accountNumber": "0783825888",
"feeChargedVnd": 125,
"chargeMethod": "PAY_AS_YOU_GO",
"quotaRemaining": {
"subscriptionQuota": 0,
"vaultQuota": 0,
"walletBalanceVnd": 1499875
},
"latencyMs": 85
}
}| Kết quả nghiệp vụ | Ví Pay-As-You-Go | Gói lượt (Tháng/Kho) |
|---|---|---|
| 200 · FOUND (Tìm thấy STK) | 245 VND / lượt | Trừ 1 lượt |
| 404 · NOT_FOUND (Không có STK) | 125 VND / lượt | Trừ 1 lượt |
| 5xx · Lỗi kỹ thuật / Upstream Timeout | 0 VND (Miễn phí 100%) | Không trừ lượt (Hoàn trả tức thì) |
04. Checklist sẵn sàng Golive
| Tiêu chí kiểm tra | Kết quả chuẩn OpenBanking |
|---|---|
| Khóa API | Được đọc từ biến môi trường máy chủ (Server-side) |
| Số tài khoản | Luôn là String để không bị mất các số 0 ở đầu |
| Mã chống lặp | Luôn sinh Idempotency-Key mới cho mỗi phiên giao dịch |
| Xử lý kết quả | Phân biệt rạch ròi giữa 200 (Có tên), 404 (Không có STK) và 503 (Bảo trì) |