Open Banking 2 — API & Chuẩn: thiết kế API ngân hàng mở

API là "sản phẩm", không phải "cổng kỹ thuật"

Trong Open Banking tổng quan ta đã thấy bức tranh lớn: ngân hàng mở dữ liệu và chức năng cho bên thứ ba (TPP — Third Party Provider) một cách có kiểm soát, có sự đồng ý của khách hàng. Nhưng "mở" bằng cách nào? Câu trả lời là API (Application Programming Interface). Và điểm mấu chốt của bài này: trong Open Banking, API không phải là một chi tiết kỹ thuật phụ trợ — API chính là sản phẩm.

Sự khác biệt về tư duy rất lớn. Một "cổng tích hợp" nội bộ có thể tạm bợ, tài liệu sơ sài vì "người dùng" là đồng nghiệp ngồi cùng tầng. API Open Banking thì ngược lại: người tiêu dùng là hàng chục, hàng trăm fintech xa lạ, họ xây sản phẩm thương mại dựa trên API của bạn và ký hợp đồng với khách cuối dựa trên giả định API ổn định. Đổi định dạng phản hồi (response) mà không báo trước là hàng loạt ứng dụng đối tác gãy — uy tín ngân hàng lãnh đủ. Vì vậy API Open Banking phải được thiết kế, đánh phiên bản, hỗ trợ và "khai tử" (deprecate) như một sản phẩm có vòng đời thật.

Tư duy API-first và các nguyên tắc thiết kế

API-first nghĩa là: thiết kế hợp đồng API (contract) trước, rồi mới hiện thực hoá backend phía sau. Contract này thường viết bằng OpenAPI (trước gọi là Swagger) — một đặc tả máy đọc được, mô tả từng endpoint, tham số, kiểu dữ liệu, mã lỗi. Contract trở thành nguồn chân lý duy nhất: đội frontend/fintech đọc nó để tích hợp, đội backend cam kết đúng nó, công cụ tự sinh mock server, SDK, và bộ test tương thích.

Một API Open Banking tốt tuân theo các nguyên tắc REST + JSON quen thuộc, nhưng với vài điểm đặc biệt quan trọng trong ngành ngân hàng:

• Tài nguyên (resource) rõ ràng, danh từ số nhiều: /accounts, /accounts/{id}/balances, /accounts/{id}/transactions, /payments. URL mô tả cái gì, HTTP method mô tả hành động gì (GET đọc, POST tạo). Tránh động từ trong URL kiểu /getAccountData.
• Versioning (đánh phiên bản): đặt phiên bản trong đường dẫn, ví dụ /open-banking/v3.1/aisp/accounts. Khi cần thay đổi phá vỡ tương thích (breaking change), phát hành v4 song song và giữ v3 chạy đủ lâu. Đây là điểm sống còn — ngân hàng không thể "vá tại chỗ" một API mà hàng trăm đối tác đang gọi.
• Phân trang (pagination): một tài khoản doanh nghiệp có thể có hàng trăm nghìn giao dịch. Không bao giờ trả tất cả trong một lần. Dùng cursor-based pagination (con trỏ next) cho dữ liệu lớn, hoặc offset/limit cho tập nhỏ. Trả kèm liên kết self, first, next, last.
• Idempotency key (khoá bất biến) — CỰC KỲ quan trọng cho thanh toán: khi TPP gửi lệnh POST /payments, mạng có thể timeout khiến TPP không biết lệnh đã thành công hay chưa và gửi lại. Nếu không xử lý, khách bị trừ tiền hai lần. Giải pháp: TPP gắn một header x-idempotency-key (một UUID duy nhất cho mỗi ý định thanh toán). Server ghi nhớ key này; nếu thấy key trùng, nó trả về kết quả của lần đầu thay vì tạo giao dịch mới. Idempotency biến "gọi lại an toàn" thành hiện thực.
• Rate limit (giới hạn tần suất): bảo vệ core banking khỏi bị TPP gọi dồn dập. Server trả header X-RateLimit-Remaining, và khi vượt ngưỡng trả mã 429 Too Many Requests kèm Retry-After. Thường phân tầng: giới hạn khác nhau cho AIS (đọc dữ liệu) và PIS (thanh toán).
• Mã lỗi chuẩn hoá: dùng đúng HTTP status (400 sai request, 401 chưa xác thực, 403 không đủ quyền/consent, 404 không thấy, 409 xung đột, 429 quá tần suất, 5xx lỗi server). Kèm thân lỗi có cấu trúc, ví dụ { "code": "Field.Missing", "message": "...", "path": "..." } để TPP xử lý tự động thay vì đoán.

Các chuẩn Open Banking trên thế giới

Nếu mỗi ngân hàng tự định nghĩa API riêng, một fintech muốn phủ 20 ngân hàng phải viết 20 bộ tích hợp khác nhau — chi phí bùng nổ, hệ sinh thái không lớn nổi. Đó là lý do chuẩn hoá (standardisation) quyết định thành bại của Open Banking. Vài khung chuẩn chính:

Điểm chung: đều dựa trên REST/JSON, đều tách bạch vai trò AISP (Account Information Service Provider — đọc dữ liệu) và PISP (Payment Initiation Service Provider — khởi tạo thanh toán), đều gắn với một profile bảo mật mạnh (OAuth2 + FAPI). Điểm khác: mức độ do luật ép buộc (EU/UK, gắn PSD2) so với do thị trường tự nguyện (Mỹ, FDX).

Việt Nam: xu hướng và định hướng là hình thành một khung Open API cho ngành ngân hàng, được Ngân hàng Nhà nước (NHNN) và các bên trong ngành thúc đẩy, nhằm chuẩn hoá kết nối ngân hàng — fintech và tăng an toàn. Ở đây tôi chỉ nêu ở mức xu hướng/định hướng: khi triển khai thực tế, đội ngũ NCB phải bám sát văn bản hướng dẫn hiện hành thay vì giả định điều khoản cụ thể. Về mặt thiết kế kỹ thuật, cách khôn ngoan là tham chiếu các chuẩn quốc tế trưởng thành (Berlin Group, OBIE) làm khuôn mẫu, để sản phẩm dễ hoà nhập khi khung trong nước định hình.

Phân loại API theo chức năng

• API dữ liệu (AIS — Account Information Service): cho phép TPP (khi có consent) đọc danh sách tài khoản, số dư (balance), lịch sử giao dịch (transactions). Đây là nền tảng cho ứng dụng tổng hợp tài khoản, quản lý chi tiêu cá nhân (PFM), chấm điểm tín dụng dựa trên dòng tiền. Xem sâu ở bài account aggregation.
• API thanh toán (PIS — Payment Initiation Service): cho phép TPP khởi tạo một lệnh chuyển tiền thay mặt khách hàng — ví dụ thanh toán đơn hàng trực tiếp từ tài khoản ngân hàng mà không qua thẻ. Đây là loại API nhạy cảm nhất, đòi hỏi idempotency và xác thực mạnh (SCA). Xem payment initiation và liên hệ nghiệp vụ chuyển tiền trong Payments & chuyển tiền.
• API sản phẩm / thông tin công khai (product info): dữ liệu không nhạy cảm, không cần consent — biểu lãi suất, biểu phí, vị trí ATM/chi nhánh, điều kiện sản phẩm vay/thẻ. Loại này dễ mở nhất và thường là bước đầu tiên của một ngân hàng khi bắt đầu Open Banking.
• Tương lai — Open Finance: mở rộng khỏi tài khoản thanh toán sang khoản vay, đầu tư, bảo hiểm, hưu trí. API cùng triết lý nhưng phạm vi dữ liệu rộng hơn nhiều.

Bảo mật ở tầng API (giới thiệu)

Bảo mật là chủ đề riêng, được đào sâu ở consent & security, ở đây chỉ giới thiệu các lớp chạm tới thiết kế API:

• OAuth2 / OpenID Connect: TPP không bao giờ thấy mật khẩu khách hàng. Thay vào đó, khách xác thực tại ngân hàng, ngân hàng cấp cho TPP một access token giới hạn phạm vi (scope) và thời hạn. Mỗi lời gọi API mang token trong header Authorization: Bearer .... Server kiểm token + kiểm consent tương ứng.
• mTLS (mutual TLS): không chỉ client kiểm server, mà server cũng kiểm chứng chỉ (certificate) của client — đảm bảo đúng TPP đã đăng ký chứ không phải kẻ mạo danh có token đánh cắp.
• Chữ ký thông điệp (message signing): với lệnh thanh toán, thân request được ký số để chống sửa đổi giữa đường (non-repudiation) — nền tảng cho FAPI.
• API Gateway: là điểm vào tập trung thực thi tất cả những điều trên (xác thực token, mTLS, rate limit, ghi log, che dữ liệu nhạy cảm) trước khi chạm tới core banking. Gateway giúp core không phải gánh logic bảo mật và cho phép áp chính sách nhất quán. Liên hệ nền tảng mật mã/kiểm soát truy cập ở access & crypto.

Sandbox và Developer Portal cho TPP

Muốn hệ sinh thái phát triển, không thể bắt fintech "test trên môi trường thật". Hai công cụ bắt buộc:

• Developer Portal: cổng cho lập trình viên bên ngoài — nơi đọc tài liệu (render từ OpenAPI), đăng ký ứng dụng (lấy client_id/secret, nộp chứng chỉ), xem quota, theo dõi trạng thái. Portal tốt là "mặt tiền bán hàng" của API.
• Sandbox: môi trường mô phỏng với dữ liệu giả, để TPP thử toàn bộ luồng (xin token, gọi AIS, khởi tạo PIS) mà không đụng tiền thật. Sandbox phải phản chiếu đúng contract production, kèm bộ dữ liệu mẫu và kịch bản lỗi để TPP test cả happy path lẫn edge case.

Portal + sandbox là mắt xích để ngân hàng thu hút và "on-board" đối tác nhanh — chủ đề hệ sinh thái được bàn ở ecosystem & fintech.

Vòng đời và quản trị API

Vì API là sản phẩm, nó có vòng đời cần quản trị (API governance):

• Design → Review → Publish: mọi API mới đi qua rà soát chuẩn thiết kế (đặt tên, mã lỗi, phân trang) và rà soát bảo mật trước khi lên portal.
• Versioning & Deprecation: không xoá đột ngột. Công bố lịch "sunset", thông báo qua portal + email, cho đối tác thời gian di chuyển sang phiên bản mới, rồi mới thu hồi.
• SLA (Service Level Agreement): cam kết uptime (ví dụ 99,9%), độ trễ p95, thời gian phản hồi sự cố. TPP dựa vào SLA để cam kết với khách của họ.
• Giám sát (monitoring): theo dõi lưu lượng theo TPP, tỷ lệ lỗi, độ trễ, phát hiện lạm dụng. Log mọi lời gọi (che dữ liệu nhạy cảm) để phục vụ đối soát và điều tra.

Ví dụ đặc tả OpenAPI rút gọn (MINH HOẠ)

Dưới đây là ví dụ minh hoạ một endpoint AIS đọc giao dịch của một tài khoản — không phải đặc tả chính thức của bất kỳ chuẩn nào, chỉ để thấy hình hài một contract.

# openapi minh hoạ — GET /accounts/{id}/transactions
paths:
  /accounts/{id}/transactions:
    get:
      summary: Lấy lịch sử giao dịch của một tài khoản
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: fromDate            # lọc theo ngày
          in: query
          schema: { type: string, format: date }
        - name: cursor              # phân trang cursor-based
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Danh sách giao dịch
        '403':
          description: Thiếu consent hợp lệ cho scope này
        '429':
          description: Vượt rate limit

Ví dụ request:

GET /open-banking/v1/accounts/ACC-8842/transactions?fromDate=2026-06-01 HTTP/1.1
Host: api.ncb.example
Authorization: Bearer eyJhbGciOi...   (access token OAuth2)
x-idempotency-key: 7f3a...(chỉ dùng cho POST payments)

Ví dụ response JSON (minh hoạ):

{
  "data": {
    "account": { "id": "ACC-8842", "currency": "VND" },
    "transactions": [
      { "txnId": "T-1001", "bookingDate": "2026-06-11",
        "amount": -250000, "kind": "debit", "desc": "QR merchant" },
      { "txnId": "T-1002", "bookingDate": "2026-06-12",
        "amount": 5000000, "kind": "credit", "desc": "Salary" }
    ]
  },
  "links": { "self": ".../transactions?cursor=A",
             "next": ".../transactions?cursor=B" },
  "meta": { "totalPages": 12 }
}

Lưu ý cấu trúc: bọc dữ liệu trong data, tách links cho phân trang, meta cho thông tin phụ. amount âm/dương thể hiện ghi nợ/ghi có — quy ước phải ghi rõ trong tài liệu. Đây là JSON minh hoạ.

Use case thực tế

Bối cảnh NCB: NCB muốn khởi động Open Banking theo lộ trình an toàn: mở API dữ liệu tài khoản/giao dịch (AIS) và thông tin sản phẩm cho một nhóm đối tác fintech được tuyển chọn, đặt nền cho PIS về sau. Yêu cầu: thiết kế bộ API theo khuôn chuẩn quốc tế (tham chiếu Berlin Group/OBIE) để dễ hoà nhập khung Open API trong nước khi định hình.

Cách làm:

1. Contract-first: đội API viết OpenAPI cho 3 nhóm — Product Info (mở trước, không cần consent), AIS (accounts/balances/transactions), và khung PIS (chưa bật, chỉ định nghĩa). Contract review qua checklist: đặt tên resource, mã lỗi chuẩn, phân trang cursor, header rate limit.
2. Versioning: cố định /open-banking/v1/... ngay từ đầu và cam kết quy tắc — thêm trường là non-breaking, đổi/xoá trường là breaking và phải lên v2 song song. Điều này tránh việc "sửa lén" contract khi đối tác đã tích hợp.
3. Idempotency: dù giai đoạn đầu chỉ có AIS (đọc, vốn idempotent tự nhiên), đội vẫn chuẩn hoá sẵn cơ chế x-idempotency-key và bảng lưu key cho nhánh PIS, để khi bật thanh toán không phải sửa kiến trúc.
4. Gateway + Portal + Sandbox: dựng API Gateway thực thi OAuth2, mTLS, rate limit (ví dụ ước lượng minh hoạ: 100 req/phút/TPP cho AIS), ghi log che số tài khoản. Developer Portal render tài liệu từ OpenAPI, cho đối tác tự đăng ký app; Sandbox có ~50 tài khoản giả và kịch bản lỗi 403/429.

Số liệu ước lượng (minh hoạ, không phải số thật): khởi động với ~5 đối tác pilot, ~20 endpoint AIS/Product; mục tiêu SLA uptime 99,9%, p95 độ trễ AIS < 800ms; onboard một TPP mới từ ~4 tuần rút còn ~1 tuần nhờ portal + sandbox tự phục vụ; giảm số phiên bản contract "gãy" xuống 0 nhờ kỷ luật versioning. Sau pilot, đánh giá bật PIS với FAPI đầy đủ.

Kết quả kỳ vọng: đối tác tích hợp nhanh, ổn định; core banking được gateway che chắn khỏi tải và rủi ro bảo mật; NCB có nền tảng chuẩn hoá sẵn sàng mở rộng sang Open Finance.

Ghi nhớ

• Trong Open Banking, API là sản phẩm: phải thiết kế, đánh phiên bản, hỗ trợ và deprecate có kỷ luật, vì người dùng là các TPP bên ngoài xây sản phẩm thương mại trên đó.
• API-first / contract-first: viết OpenAPI (Swagger) trước làm nguồn chân lý; nó sinh mock, SDK, test và tài liệu portal.
• Nguyên tắc thiết kế ngân hàng: REST/JSON, resource danh từ số nhiều, versioning trong path, phân trang (cursor cho dữ liệu lớn), idempotency key (bắt buộc cho thanh toán để chống trừ tiền hai lần), rate limit (429), mã lỗi chuẩn.
• Các chuẩn quốc tế: OBIE (UK), Berlin Group NextGenPSD2 (EU), STET (Pháp), FDX (Mỹ) — đều tách AISP/PISP và gắn profile bảo mật mạnh. Việt Nam đang ở mức định hướng khung Open API do NHNN/ngành thúc đẩy — bám văn bản hiện hành, đừng giả định điều khoản.
• Phân loại API: AIS (dữ liệu tài khoản/giao dịch), PIS (khởi tạo thanh toán), Product Info (công khai, dễ mở trước), và tương lai Open Finance (vay/đầu tư/bảo hiểm).
• Bảo mật tầng API: OAuth2/OIDC, mTLS, chữ ký thông điệp, thực thi tập trung tại API Gateway — chi tiết ở ob-03.
• Sandbox + Developer Portal là mắt xích on-board TPP nhanh; vòng đời & governance (design→publish→version→deprecate), SLA và giám sát giữ API đáng tin cậy.

Nguồn tham khảo

• OpenAPI Specification — https://spec.openapis.org/ (đặc tả hợp đồng API máy đọc được, tiền thân là Swagger)
• UK Open Banking (OBIE) — Open Banking Standard, Read/Write API Specifications — https://www.openbanking.org.uk/
• Berlin Group — NextGenPSD2 XS2A Framework — https://www.berlin-group.org/
• Financial-grade API (FAPI), OpenID Foundation — https://openid.net/wg/fapi/
• OAuth 2.0 Authorization Framework — RFC 6749 — https://datatracker.ietf.org/doc/html/rfc6749
• HTTP Semantics (mã trạng thái, phương thức) — RFC 9110 — https://datatracker.ietf.org/doc/html/rfc9110
• Financial Data Exchange (FDX) API — https://financialdataexchange.org/