Đến nội dung
BankGateway
Console ↗
Tìm kiếm tài liệu & API
Bắt đầu
Tổng quan dịch vụ

Cổng API Tra cứu số tài khoản Napas 24/7 theo chuẩn OpenBanking quốc tế. Độ trễ cực thấp O(1) Cache, xác thực Zero-Trust và chữ ký số Ed25519.

Bắt đầu
Bắt đầu nhanh (Quickstart)

Hướng dẫn thực hiện cuộc gọi API tra cứu số tài khoản đầu tiên trong vòng 3 phút bằng cURL, Node.js hoặc Python.

Xác thực & Bảo mật
Xác thực API Key

Cơ chế bảo mật Server-to-Server bằng Header X-API-Key, nguyên tắc giữ bí mật và quy trình thu hồi / cấp phát lại khóa.

Xác thực & Bảo mật
Chữ ký số Ed25519

Đảm bảo tính toàn vẹn và chống giả mạo dữ liệu ngân hàng bằng chữ ký mật mã Ed25519 đính kèm trong mỗi phản hồi.

Xác thực & Bảo mật
Chống trùng lặp (Idempotency)

Sử dụng Header Idempotency-Key chuẩn RFC 8470 để đảm bảo không bị trừ tiền hai lần khi mạng chập chờn hoặc retry.

API Tra cứu ngân hàngPOST
Tra cứu tài khoản

Đặc tả kỹ thuật Endpoint POST /api/v1/lookup. Tra cứu thời gian thực tên chủ tài khoản ngân hàng.

API Tra cứu ngân hàngPOST
Tra cứu theo lô & Webhook

Gửi danh sách hàng nghìn STK trong một request, nhận thông báo kết quả bất đồng bộ qua Webhook kèm chữ ký số.

API Tra cứu ngân hàngGET
Danh sách 68 ngân hàng

Danh mục mã ngân hàng (bankCode), mã BIN Napas, tên đầy đủ và tình trạng kết nối thời gian thực.

↑ ↓ Đ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/API Tra cứu ngân hàng

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/lookupX-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.org/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 ↗