Đế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:Tổng quan dịch vụ ▾
Tài liệu/Bắt đầu

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.

Kiến trúc kết nối tinh giản & mạnh mẽ

BankGateway cung cấp giao thức RESTful API đồng nhất trên nền HTTPS, cho phép ứng dụng của bạn 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 chỉ bằng 1 HTTP POST duy nhất.

Base URL Production
https://api.bankgateway.org
Tiêu chuẩnChi tiết triển khai
Giao thứcHTTPS TLS 1.3 · RESTful JSON · HTTP/2
Xác thựcHeader X-API-Key + Zero-Trust IP Whitelisting
Chữ ký sốEd25519 Cryptographic Signature trong payload
Chống trùng lặpChuẩn Idempotency RFC 8470 với Idempotency-Key
Tốc độ phản hồi0ms - 2ms (Redis L1 / SQLite L2) | 45ms - 150ms (Upstream MB/Napas)
Định dạng STKString giữ nguyên số 0 ở đầu (ví dụ: "0783825888")

Quy trình tích hợp 4 bước

  1. 01
    1. Khởi tạo tác vụ

    Ứng dụng tạo mã Idempotency-Key (UUID v4) và chuẩn bị mã ngân hàng (bankCode) cùng số tài khoản (accountNumber).

  2. 02
    2. Gửi lệnh từ Backend

    Backend gọi POST /api/v1/lookup kèm header X-API-Key. Gateway kiểm tra hạn mức và định tuyến qua bộ đệm Two-Tier Cache.

  3. 03
    3. Nhận phản hồi JSON sạch

    Nhận kết quả tên chủ tài khoản, mã xác thực Ed25519, chi phí quyết toán và số dư khả dụng cập nhật tức thì.

  4. 04
    4. Kiểm tra chữ ký & Hoàn tất

    Lưu trữ requestId và đối soát số dư với sổ cái (Ledger) minh bạch.

Danh mục API cốt lõi

Chức năngPhương thức / EndpointMục đích
Tra cứu tài khoản NapasPOST /api/v1/lookupTra cứu tên chủ tài khoản ngân hàng đơn lẻ (Real-time 0ms-80ms)
Tra cứu hàng loạt (Batch)POST /api/v1/lookup/batchXử lý bất đồng bộ tối đa 1.000 STK/lần kèm Webhook HMAC
Nhật ký & Thống kê tra cứuGET /api/v1/lookup/logsTruy vấn log tra cứu phân trang và thống kê hiệu suất
Kiểm tra số dư & QuotaGET /api/v1/wallet/balanceTruy vấn số dư ví khả dụng, gói tháng và hạn mức API Key
Sao kê sổ cái (Ledger)GET /api/v1/wallet/statementĐối soát lịch sử biến động số dư và các khoản khấu trừ minh bạch
Giải mã VietQR EMVCoPOST /api/v1/vietqr/decodeGiải mã chuỗi QR Code chuẩn Napas ra ngân hàng và STK
Danh mục ngân hàngGET /api/v1/banksDanh sách 68 Ngân hàng / Công ty tài chính, mã BIN Napas và logo nhận diện
Tạo phiên Checkout VietQRPOST /api/v1/payment-gateway/checkoutKhởi tạo đơn thanh toán VietQR tự động và nhận link /pay/[id]
Đồng bộ lịch sử giao dịchGET /api/v1/gateway/historyLấy lịch sử biến động giao dịch MBBank/Techcombank theo token
Quản lý Webhook OutboxGET /api/v1/integrations/webhooksCấu hình webhook nhận sự kiện, xoay secret và retry job lỗi

Tài liệu tiếp theo

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 ↗