Đến nội dung
BankGatewayBankGateway
Console ↗
↑ ↓ Điều hướng↵ ChọnEsc Đóng
Mục lục tài liệu:Bắt đầu nhanh (Quickstart) ▾
Tài liệu›Bắt đầu›Bắt đầu nhanh (Quickstart)
Phiên bản:v1.0.5 (Chính thức)

Bắt đầu nhanh (Quickstart)

Hướng dẫn gọi API tra cứu số tài khoản đầu tiên với cURL hoặc mã nguồn chỉ trong 3 phút.

01. Lấy API Key

  1. 01
    Mở Cổng quản trị API

    Truy cập Dashboard > Khóa API & IP Whitelist để lấy API Key (tiền tố bg_live_...).

  2. 02
    Cấu hình IP Whitelist (Khuyến nghị)

    Thêm địa chỉ IP máy chủ của bạn để kích hoạt cơ chế phòng vệ Zero-Trust.

  3. 03
    Lưu vào biến môi trường

    Đặt BANKGATEWAY_API_KEY trong file .env trên máy chủ. Không lưu vào Git repository.

02. Thực hiện lệnh 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"
  }'

03. Cấu trúc phản hồi

Dưới đây là mẫu JSON trả về khi tìm thấy tài khoản (HTTP 200) và khi không tìm thấy tài khoản (HTTP 404):

200 · Tìm thấy tài khoản (FOUND)
{
  "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"
  }
}
404 · Không tìm thấy (NOT_FOUND)
{
  "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
  }
}
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ì)

04. Checklist sẵn sàng Golive

Tiêu chí kiểm traKết quả chuẩn OpenBanking
Khóa APIĐược đọc từ biến môi trường máy chủ (Server-side)
Số tài khoảnLuôn là String để không bị mất các số 0 ở đầu
Mã chống lặpLuôn sinh Idempotency-Key mới cho mỗi phiên giao dịch
Xử lý kết quảPhân biệt rạch ròi giữa 200 (Có tên), 404 (Không có STK) và 503 (Bảo trì)
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 ↗