Tài liệu API

REST API để tạo yêu cầu thanh toán cho từng đơn và nhận webhook khi tiền về tài khoản ngân hàng của bạn. Request và response đều là JSON, xác thực bằng API key.

Base URL

Mọi endpoint trong tài liệu này tính từ địa chỉ:

https://app.bankopenapi.com/api/v1

Cách hoạt động

Liên kết tài khoản ngân hàng trong app, xác nhận bằng OTP ngân hàng gửi. Tiền vẫn đi thẳng vào tài khoản của bạn; BankOpenAPI chỉ nhận thông tin giao dịch.
Hệ thống của bạn tạo yêu cầu thanh toán cho mỗi đơn qua API. BankOpenAPI trả về số tiền, số tài khoản nhận và một mã như TT7K3M9Q để ghi trong nội dung chuyển khoản.
Bạn hiện mã VietQR cho người trả. Quét mã là app ngân hàng điền sẵn số tiền và nội dung.
Tiền về, BankOpenAPI đọc mã trong nội dung, khớp với yêu cầu và gửi webhook payment_request.paid tới endpoint của bạn. Hệ thống của bạn chuyển đơn sang "đã thanh toán".

Quy ước chung

Body của request và response là JSON. Gửi kèm header Content-Type: application/json khi có body.
Tên trường trong JSON viết kiểu camelCase (amountReceived, expiresAt). Tham số query viết kiểu snake_case (order_id, starting_after).
Mỗi đối tượng có id mang tiền tố theo loại: pr_ (yêu cầu thanh toán), ba_ (tài khoản ngân hàng), txn_ (giao dịch), evt_ (sự kiện webhook), we_ (webhook endpoint); và trường object ghi tên loại.
Số tiền là số nguyên, đơn vị VND (150000 là 150.000 VND). Không dùng số thập phân.
Thời gian là chuỗi ISO 8601 theo giờ UTC, ví dụ 2026-11-05T03:20:11.000Z (10:20 giờ Việt Nam).
Danh sách trả về dạng { "object": "list", "data": [...], "hasMore": false }, mới nhất trước.
Lỗi trả mã HTTP 4xx, 5xx kèm { "error": { "code": "...", "message": "..." } }. Xem Lỗi và mã lỗi.

Đang có và sắp có

Tính năng	Trạng thái
Xác thực bằng API key, `GET /v1/account`	Đang chạy
API yêu cầu thanh toán: tạo, xem, liệt kê, hủy	Đang chạy
Webhook theo chuẩn Standard Webhooks, 5 loại sự kiện, retry khoảng 27 giờ	Đang chạy
Skill cho AI agent, MCP server	Mới
API tài khoản ngân hàng (`/v1/bank-accounts`), chỉ đọc	Mới
API giao dịch (`/v1/transactions`), chỉ đọc	Mới
API quản lý webhook endpoint (`/v1/webhook-endpoints`)	Mới
Header `Idempotency-Key` cho request tạo mới	Mới
Sandbox: API key `boa_test_`, giả lập tiền vào và thanh toán (`/v1/test/*`)	Mới
API sự kiện (`/v1/events`), JSON Schema cho payload webhook	Mới
SDK chính thức	Sắp có

Liên kết tài khoản ngân hàng (chủ tài khoản xác nhận bằng OTP) và tạo API key làm trong app tại app.bankopenapi.com. Cần endpoint nào sớm, gửi email tới teams@bankopenapi.com.

Tài liệu API BankOpenAPI