Đến nội dung
BankGatewayBankGateway
Console ↗
↑ ↓ Điều hướng↵ ChọnEsc Đóng
Mục lục tài liệu:Tra cứu số tài khoản ▾
Tài liệu›Danh mục API›Tra cứu số tài khoản
Phiên bản:v1.0.5 (Chính thức)

API cốt lõi tra cứu tên chủ tài khoản thụ hưởng tại 68 Ngân hàng / Công ty tài chính. Hỗ trợ phản hồi siêu tốc từ Two-Tier Cache.

POST/api/v1/lookupHeader: X-API-Key

Thông số Request

HeaderBắt buộcMô tả & Chuẩn
X-API-KeyBắt buộcKhóa bí mật API cấp riêng cho tài khoản. Chỉ truyền từ server-to-server.
Content-TypeBắt buộcapplication/json; charset=utf-8
Idempotency-KeyKhuyến nghị caoUUID 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ínhKiểu dữ liệuBắt buộcMô tả chi tiết
bankCodestringBắt buộcMã ngân hàng (ví dụ: MB, VCB, TCB, ACB, CTG, BIDV, VPB,...). Hệ thống tự động chuẩn hóa chữ hoa.
accountNumberstringBắt buộcSố tài khoản thụ hưởng. Luôn truyền dạng chuỗi String để giữ nguyên các số 0 ở đầu.
JSON Body
{
  "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ố:

JSON
{
  "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 tinKiểuMô tả nghiệp vụ
requestIdstringMã định danh duy nhất của lượt tra cứu dùng để đối soát.
bankCodestringMã viết tắt chuẩn của ngân hàng (MB, VCB,...).
bankNamestringTên đầy đủ của ngân hàng thụ hưởng.
accountNumberstringSố tài khoản thụ hưởng được xác thực.
accountNamestringHọ và tên chủ tài khoản viết hoa không dấu theo chuẩn Napas.
cachedbooleantrue nếu kết quả được tối ưu phản hồi siêu tốc từ Cache L1/L2.
sourcestringNguồn dữ liệu: L1_CACHE, L2_DATABASE hoặc LIVE_UPSTREAM.
latencyMsnumberĐộ trễ xử lý thực tế tính bằng milliseconds.
signaturestringChữ ký số Ed25519 bảo chứng tính toàn vẹn của kết quả.
feeChargedVndnumberSố tiền đã quyết toán cho lượt gọi này (0 VND nếu dùng gói).
quotaRemainingobjectSố 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:

JSON
{
  "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:

502 · UPSTREAM_FAILURE
{
  "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-GoGói lượt (Tháng/Kho)
200 · FOUND (Tìm thấy STK)245 VND / lượtTrừ 1 lượt
404 · NOT_FOUND (Không có STK)125 VND / lượtTrừ 1 lượt
5xx · Lỗi kỹ thuật / Upstream Timeout0 VND (Miễn phí 100%)Không trừ lượt (Hoàn trả tức thì)
Tài liệu phát hành theo chuẩn OpenBanking 2.0 · Cập nhật v1.0.5 (Chính thức)Góp ý tài liệu & Báo lỗi ↗