Thông số Request
| Header | Bắt buộc | Mô tả & Chuẩn |
|---|---|---|
| X-API-Key | Bắt buộc | Khóa bí mật API cấp riêng cho tài khoản. Chỉ truyền từ server-to-server. |
| Content-Type | Bắt buộc | application/json; charset=utf-8 |
| Idempotency-Key | Khuyến nghị cao | UUID v4 duy nhất cho mỗi giao dịch (RFC 8470). Chống trừ tiền trùng lặp khi mạng lag. |
| Thuộc tính | Kiểu dữ liệu | Bắt buộc | Mô tả chi tiết |
|---|---|---|---|
| bankCode | string | Bắt buộc | Mã ngân hàng (ví dụ: MB, VCB, TCB, ACB, CTG, BIDV, VPB,...). Hệ thống tự động chuẩn hóa chữ hoa. |
| accountNumber | string | Bắt buộc | Số tài khoản thụ hưởng. Luôn truyền dạng chuỗi String để giữ nguyên các số 0 ở đầu. |
{
"bankCode": "MB",
"accountNumber": "0783825888"
}Ví dụ 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"
}'200 OK · Tìm thấy tài khoản (FOUND)
Khi số tài khoản tồn tại và hợp lệ tại ngân hàng đích, API trả về thông tin tên chủ tài khoản thụ hưởng kèm chứng thực số:
{
"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"
}
}| Trường thông tin | Kiểu | Mô tả nghiệp vụ |
|---|---|---|
| requestId | string | Mã định danh duy nhất của lượt tra cứu dùng để đối soát. |
| bankCode | string | Mã viết tắt chuẩn của ngân hàng (MB, VCB,...). |
| bankName | string | Tên đầy đủ của ngân hàng thụ hưởng. |
| accountNumber | string | Số tài khoản thụ hưởng được xác thực. |
| accountName | string | Họ và tên chủ tài khoản viết hoa không dấu theo chuẩn Napas. |
| cached | boolean | true nếu kết quả được tối ưu phản hồi siêu tốc từ Cache L1/L2. |
| source | string | Nguồn dữ liệu: L1_CACHE, L2_DATABASE hoặc LIVE_UPSTREAM. |
| latencyMs | number | Độ trễ xử lý thực tế tính bằng milliseconds. |
| signature | string | Chữ ký số Ed25519 bảo chứng tính toàn vẹn của kết quả. |
| feeChargedVnd | number | Số tiền đã quyết toán cho lượt gọi này (0 VND nếu dùng gói). |
| quotaRemaining | object | Số dư ví và hạn mức lượt gói còn lại của tài khoản. |
404 Not Found · Không tìm thấy (NOT_FOUND)
Khi ngân hàng đích xác nhận số tài khoản không tồn tại, API trả về mã lỗi NOT_FOUND:
{
"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
}
}5xx · Lỗi kỹ thuật / Upstream Timeout
Khi hệ thống liên ngân hàng Napas tạm thời quá tải hoặc timeout, API trả về mã lỗi 502/504. Các trường hợp này hoàn toàn miễn phí và không bị trừ lượt:
{
"success": false,
"error": {
"code": "UPSTREAM_FAILURE",
"message": "Hệ thống liên ngân hàng Napas tạm thời không phản hồi; yêu cầu có thể thử lại an toàn.",
"requestId": "REQ_20261017_9921FA82"
}
}| 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ì) |