Đế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ạo đơn thanh toán QR (v1 / v2) ▾
Tài liệu/Thanh toán tự động

Tạo đơn thanh toán QR (v1 / v2)

Khởi tạo phiên thanh toán QR Hosted (hỗ trợ LIVE & SANDBOX, chống trùng đơn 409 IDEMPOTENCY_CONFLICT và Form POST Redirect).

POST/api/v1/payment-gateway/checkoutX-API-Key

Tham số Body (JSON hoặc Form POST)

TrườngKiểuBắt buộcMô tả
merchantIdstringCóMã định danh cửa hàng (VD: BGW_A1B2C3D4).
orderIdstringCóMã đơn hàng duy nhất (1-64 ký tự, A-Za-z0-9_.-). Gửi lại cùng orderId nhưng khác amount/URL trả 409 IDEMPOTENCY_CONFLICT.
amountnumberCóSố tiền VND nguyên dương (2.000 – 500.000.000).
timestampnumberCóUnix timestamp (ms). Chênh lệch tối đa ±5 phút.
environmentstringKhôngLIVE (mặc định, ký bằng sk_live_) hoặc SANDBOX (ký bằng sk_test_).
signatureVersionstringKhông"1" (mặc định) hoặc "2" (bắt buộc khi ghi đè returnUrl/cancelUrl/webhookUrl).
signaturestringCóv1: HMAC_SHA256(key, "${merchantId}|${orderId}|${amount}|${timestamp}"). v2: ký thêm environment và các URL override.
returnUrl / cancelUrl / webhookUrlstringKhôngChỉ được ghi đè khi dùng signatureVersion="2" (HTTPS trong production, chống SSRF).

Tích hợp HTML Form POST (Chuẩn SePay / 9Pay)

Ngoài REST API trả JSON, bạn có thể submit thẳng từ form HTML (ký ở server PHP/Node) tới POST /api/v1/payment-gateway/checkout/form. Hệ thống xác thực chữ ký và chuyển hướng HTTP 303 tới trang thanh toán QR.

PHP + HTML Form
<?php
$merchantId = getenv("BGW_MERCHANT_ID");
$secretKey  = getenv("BGW_SECRET_KEY");
$orderId    = "DH_" . time();
$amount     = 50000;
$timestamp  = round(microtime(true) * 1000);
$signature  = hash_hmac("sha256", "$merchantId|$orderId|$amount|$timestamp", $secretKey);
?>
<form method="POST" action="https://api.bankgateway.org/api/v1/payment-gateway/checkout/form">
  <input type="hidden" name="merchantId" value="<?= $merchantId ?>" />
  <input type="hidden" name="orderId" value="<?= $orderId ?>" />
  <input type="hidden" name="amount" value="<?= $amount ?>" />
  <input type="hidden" name="timestamp" value="<?= $timestamp ?>" />
  <input type="hidden" name="signature" value="<?= $signature ?>" />
  <button type="submit">Thanh toán VietQR</button>
</form>

Code mẫu REST API (Node.js / PHP / Python)

import crypto from "node:crypto";

const merchantId = process.env.BGW_MERCHANT_ID;
const secretKey = process.env.BGW_SECRET_KEY;
const orderId = "DH_10001";
const amount = 50000;
const timestamp = Date.now();

const signature = crypto
  .createHmac("sha256", secretKey)
  .update(`${merchantId}|${orderId}|${amount}|${timestamp}`)
  .digest("hex");

const res = await fetch("https://api.bankgateway.org/api/v1/payment-gateway/checkout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ merchantId, orderId, amount, timestamp, signature })
});
const json = await res.json();
// Redirect khách sang json.data.checkoutUrl
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 ↗