Đế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 theo lô & Webhook ▾
Tài liệu/API Tra cứu ngân hàng

API xử lý bất đồng bộ (Async Batch) lên tới 1.000 số tài khoản/lần. Tự động gửi Webhook (HMAC-SHA256) về máy chủ của bạn khi hoàn tất mà không cần giữ kết nối HTTP treo liên tục.

POST/api/v1/lookup/batchX-API-Key

Tổng quan cơ chế Async Webhook

Đối với các danh sách lớn (hàng trăm đến hàng ngàn tài khoản), thay vì mở kết nối HTTP chờ liên tục, bạn chỉ cần gửi danh sách kèm `webhookUrl`. Hệ thống sẽ phân luồng ngầm an toàn và tự động gửi thông báo POST kèm chữ ký số HMAC-SHA256 về máy chủ của bạn khi hoàn tất.

Thông số Request khởi tạo Batch

Thuộc tínhKiểu dữ liệuBắt buộcMô tả chi tiết
itemsarrayBắt buộcMảng danh sách tài khoản (tối đa 1.000 tài khoản). Mỗi phần tử gồm bankCode, accountNumber, clientRef (tùy chọn).
webhookUrlstringTùy chọnURL HTTPS máy chủ của bạn để nhận kết quả khi job hoàn tất.
webhookSecretstringTùy chọnKhóa bí mật tùy chỉnh để ký HMAC-SHA256. Nếu bỏ trống, hệ thống sử dụng khóa mặc định của tài khoản.
cURL
curl -X POST 'https://api.bankgateway.org/api/v1/lookup/batch' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "webhookUrl": "https://your-domain.com/api/webhooks/bankgateway",
    "webhookSecret": "your_secure_secret_token_123",
    "items": [
      { "bankCode": "MB", "accountNumber": "0783825888", "clientRef": "EMP_01" },
      { "bankCode": "VCB", "accountNumber": "1012345678", "clientRef": "EMP_02" }
    ]
  }'

202 Accepted · Tiếp nhận xử lý ngầm

JSON
{
  "success": true,
  "message": "Yêu cầu tra cứu hàng loạt đã được tiếp nhận và đưa vào hàng đợi xử lý",
  "data": {
    "jobId": "BATCH_1793352313937_acd1c46c",
    "totalItems": 2,
    "status": "PENDING",
    "statusUrl": "/api/v1/lookup/batch/BATCH_1793352313937_acd1c46c",
    "webhookUrl": "https://your-domain.com/api/webhooks/bankgateway"
  }
}

Cấu trúc Webhook Payload gửi về máy chủ của bạn

Khi job đạt trạng thái hoàn tất (COMPLETED hoặc FAILED), BankGateway sẽ gửi một yêu cầu HTTP POST tới `webhookUrl` của bạn với các headers bảo mật:

HeaderMô tả
X-BGW-EventTên sự kiện: batch.completed, batch.failed hoặc batch.cancelled
X-BGW-Job-IdMã định danh công việc (Job ID)
X-BGW-TimestampThời gian gửi (Unix timestamp tính bằng giây)
X-BGW-SignatureChữ ký số HMAC-SHA256 theo payload thô (Raw Body)
X-BGW-Signature-256Chuẩn Stripe format: t={timestamp},v1={signature}
Webhook Payload
{
  "event": "batch.completed",
  "timestamp": 1793352320,
  "jobId": "BATCH_1793352313937_acd1c46c",
  "tenantId": "ten_01jk98m",
  "data": {
    "jobId": "BATCH_1793352313937_acd1c46c",
    "totalItems": 2,
    "processedItems": 2,
    "successItems": 2,
    "failedItems": 0,
    "status": "COMPLETED",
    "results": [
      {
        "bankCode": "MB",
        "accountNumber": "0783825888",
        "clientRef": "EMP_01",
        "status": "SUCCESS",
        "outcome": "FOUND",
        "accountName": "NGUYEN VAN HOANG",
        "message": "Tra cứu thành công"
      }
    ]
  }
}

Xác minh chữ ký Webhook (Code mẫu)

Node.js
// Node.js Express Webhook Verification
import crypto from "crypto";

app.post("/api/webhooks/bankgateway", (req, res) => {
  const signature = req.headers["x-bgw-signature"];
  const rawBody = JSON.stringify(req.body);
  const secret = "your_secure_secret_token_123";

  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  if (crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"))) {
    console.log("Xác minh Webhook thành công! Xử lý job:", req.body.jobId);
    return res.status(200).json({ received: true });
  } else {
    return res.status(401).send("Invalid Webhook Signature");
  }
});

Bắn lại Webhook thủ công (Manual Redelivery)

Nếu máy chủ của bạn gặp sự cố bảo trì khi Webhook gửi đến, bạn có thể chủ động kích hoạt gửi lại bất kỳ lúc nào:

cURL
curl -X POST 'https://api.bankgateway.org/api/v1/lookup/batch/BATCH_1793352313937_acd1c46c/retry-webhook' \
  -H 'X-API-Key: YOUR_API_KEY'
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 ↗