# API thanh toán ngân hàng Pay2S: BankHub là gì và cách tích hợp

- Link: https://mail.hoadontudong.com.vn/api-thanh-toan-ngan-hang-pay2s/
- Published: 2026-10-14T05:27:03+07:00
- Author: Hóa Đơn Tự Động

API thanh toán ngân hàng Pay2S là lớp kết nối giúp website, phần mềm bán hàng và
hệ thống doanh nghiệp làm việc với tài khoản ngân hàng thông qua BankHub. Thay vì
để nhân viên đăng nhập nhiều cổng ngân hàng, hệ thống đối tác có thể quản lý luồng
liên kết, nhận thông báo giao dịch, đối soát và cập nhật trạng thái trong một kiến
trúc thống nhất. Trên hoadontudong.com.vn, chủ đề này đặc biệt hữu ích cho doanh
nghiệp muốn nối dữ liệu thanh toán với đơn hàng, hóa đơn và quy trình vận hành nội
bộ.

Tài liệu Pay2S chia Partner API thành các nhóm xác thực, ngân hàng, webhook và Analytics.
Mỗi nhóm giải quyết một phần khác nhau, vì vậy tích hợp tốt không chỉ là gọi một
endpoint tạo tài khoản. Backend cần lấy token đúng cách, liên kết đúng tài khoản,
lưu ID bản ghi của Pay2S, đăng ký webhook phù hợp và có cơ chế chống trùng khi ngân
hàng gửi cùng một giao dịch nhiều lần.

## BankHub giải quyết bài toán gì trong hệ thống thanh toán

Trong một mô hình bán hàng có website, cửa hàng và nhiều tài khoản nhận tiền, dữ
liệu thanh toán thường nằm rời rạc. Đơn hàng nằm ở phần mềm bán hàng, giao dịch 
nằm ở ngân hàng, còn nhân viên phải kiểm tra thủ công để biết khoản tiền nào thuộc
đơn nào. BankHub tạo một lớp trung gian có thể liên kết tài khoản ngân hàng, xác
định trạng thái tài khoản và đẩy giao dịch về endpoint do đối tác đăng ký. Điều 
này giúp backend chủ động tổ chức quy tắc khớp mã đơn, số tiền, tài khoản nhận và
thời gian.

BankHub không tự thay thế nghiệp vụ của doanh nghiệp. Pay2S cung cấp kết nối và 
dữ liệu, còn đối tác phải quyết định đơn nào được xác nhận, cách lưu giao dịch, 
cách cấp quyền và cách xử lý ngoại lệ. Khi giao dịch chưa đủ thông tin hoặc webhook
chưa rõ, hệ thống nên đưa dữ liệu vào hàng chờ để kiểm tra thay vì đánh dấu thanh
toán thành công chỉ dựa trên một trường đơn lẻ.

## Kiến trúc xác thực và các loại token

Partner API dùng Base URL `https://api-partner.pay2s.vn` trong `Production` và có
môi trường `UAT` riêng. Backend lấy `Access Key` và `Secret Key` tại Merchant, khu
vực Bankhub, sau đó gửi `Basic Authentication` tới endpoint /v1/auth/authorize để
nhận `Bearer Token` tạm thời. Token hiện có thời hạn được trả ở `expires_in`, tài
liệu minh họa là 3600 giây. Khi gọi các API ngân hàng, webhook hoặc metrics, backend
gửi `Authorization: Bearer` cùng token này.

Webhook token là một loại thông tin khác. `Bearer Token` dùng theo chiều đối tác
gọi Pay2S, còn webhook token được Pay2S gửi đến endpoint của đối tác khi có giao
dịch hoặc sự kiện. Không trộn hai token, không đưa `Secret Key` vào trình duyệt 
và không ghi token đầy đủ vào log. Hướng dẫn riêng về [xác thực API thanh toán ngân hàng Pay2S](https://hoadontudong.com.vn/xac-thuc-api-thanh-toan-ngan-hang-pay2s/)
sẽ đi sâu vào `Basic Auth`, hết hạn token và cách xử lý lỗi `401`.

## Từ liên kết ngân hàng đến nhận giao dịch

![Minh họa luồng liên kết ngân hàng đến nhận giao dịch qua BankHub](https://hoadontudong.
com.vn/wp-content/uploads/2026/10/bankhub-pillar-inline-bank-link-imagegen.png)

Từ liên kết ngân hàng đến nhận giao dịch

Sau khi có `Bearer Token`, đối tác có thể gọi nhóm /v1/banks để thêm, xác nhận OTP,
lấy danh sách, bật tắt hoặc xóa liên kết. Trường id trong danh sách là ID bản ghi
tài khoản trên Pay2S, không phải số tài khoản; ID này được dùng để gắn webhook giao
dịch. Tùy ngân hàng, luồng có thể dùng `OpenAPI` hoặc `RPA`, tài khoản cá nhân hoặc
doanh nghiệp, và có thể phát sinh OTP. Do đó không nên coi phản hồi ban đầu là bằng
chứng tài khoản đã hoạt động.

Bước tiếp theo là đăng ký /v1/webhooks với `user_bank_id`, `webhook_url` và loại
giao dịch `IN`, `OUT` hoặc `ALL`. Pay2S gửi payload giao dịch về endpoint đã đăng
ký, kèm token riêng. Backend cần xác thực token, lưu payload bền vững, trả ACK đúng
quy ước và xử lý nghiệp vụ trong hàng đợi. Nội dung webhook giao dịch khác hoàn 
toàn webhook trạng thái Hosted Link; bài [webhook giao dịch ngân hàng Pay2S](https://hoadontudong.com.vn/webhook-giao-dich-ngan-hang-pay2s/)
sẽ tách riêng hai luồng này.

## Thiết kế dữ liệu và chống trùng

![Minh họa thiết kế dữ liệu giao dịch và chống trùng BankHub](https://hoadontudong.
com.vn/wp-content/uploads/2026/10/bankhub-pillar-inline-dedupe-imagegen.png)

Thiết kế dữ liệu và chống trùng

Một giao dịch ngân hàng nên được lưu với khóa duy nhất gồm ID giao dịch hoặc checksum,
mã ngân hàng, tài khoản nhận, loại giao dịch, số tiền, thời gian và nội dung chuyển
khoản. Nếu payload có `paymentCode`, `billNumber`, `partnerRefId` hoặc thông tin`
extraData`, hãy lưu ở các trường tùy chọn và không giả định giao dịch nào cũng có
đủ. Số tài khoản, mã giao dịch và các giá trị có số 0 đầu phải giữ dạng chuỗi.

Webhook có thể được gửi lại khi endpoint timeout, trả lỗi hoặc phản hồi ngoài `2xx`.
Vì vậy receiver phải kiểm tra trùng trước khi tạo tác động không thể đảo ngược như
xác nhận đơn, cấp quyền dịch vụ hoặc khởi tạo hóa đơn. Khi đã lưu bền vững, trả `
2xx` cho cùng event hoặc transaction đã xử lý để Pay2S không tiếp tục retry. Nếu
chưa lưu thành công, trả lỗi và để cơ chế gửi lại làm việc.

## Quy trình triển khai theo giai đoạn

![Minh họa quy trình triển khai API thanh toán ngân hàng Pay2S theo giai đoạn](https://
hoadontudong.com.vn/wp-content/uploads/2026/10/bankhub-pillar-inline-deploy-imagegen.
png)

Quy trình triển khai API thanh toán ngân hàng Pay2S

Giai đoạn một là chuẩn bị môi trường và bảo mật. Tách khóa `UAT` khỏi `Production`,
đặt `Secret Key` trong biến môi trường, giới hạn quyền truy cập và xác định URL 
HTTPS nhận webhook. Giai đoạn hai là gọi authorize, thêm một tài khoản thử nghiệm,
xác nhận OTP nếu cần, đọc lại danh sách và ghi nhận `user_bank_id`. Giai đoạn ba
là tạo webhook giao dịch, gửi giao dịch mẫu và kiểm tra cả trường bắt buộc lẫn trường
tùy chọn.

Giai đoạn bốn là nối transaction với đơn hàng. Hệ thống cần có một mã thanh toán
hoặc quy tắc nội dung chuyển khoản rõ ràng, nhưng không nên chỉ dựa vào nội dung
nếu nghiệp vụ yêu cầu kiểm soát chặt. Hãy kiểm tra thêm tài khoản nhận, số tiền 
và trạng thái tài khoản. Giai đoạn năm là chạy đối soát định kỳ và quan sát Analytics
để biết endpoint nào chậm, lỗi ở đâu và webhook nào cần gửi lại.

## BankHub phù hợp với những mô hình nào

Cửa hàng bán lẻ có thể dùng BankHub để nhận biến động tiền vào, đối chiếu mã đơn
và giảm việc kiểm tra sao kê thủ công. Website thương mại điện tử có thể dùng webhook
để cập nhật trạng thái thanh toán, sau đó chuyển đơn sang giao hàng hoặc quy trình
hóa đơn. Nền tảng thu hộ có thể phân tách tài khoản theo khách hàng, cửa hàng hoặc
mã tham chiếu. Mỗi mô hình cần đặt giới hạn riêng về quyền, tài khoản và xử lý ngoại
lệ.

Nếu doanh nghiệp chỉ cần khách tự liên kết tài khoản, Hosted Link và `SDK` có thể
giảm việc thu thập thông tin nhạy cảm ở frontend. Nếu hệ thống đã có backend mạnh
và cần kiểm soát request chi tiết, API trực tiếp phù hợp hơn. Hai lựa chọn có thể
cùng nằm trong một sản phẩm nhưng không nên trộn callback, session ID, `user_bank_id`
và account ID. Bài [Pay2S BankHub Hosted Link và SDK](https://hoadontudong.com.vn/pay2s-bankhub-hosted-link-sdk/)
giải thích luồng dành cho form do Pay2S cung cấp.

## Những giới hạn cần nói rõ trong bài viết và khi triển khai

Tài liệu Pay2S có phần đánh dấu các response minh họa, sự khác nhau giữa `Production`
và `UAT`, cùng các trường cần xác nhận với backend theo từng ngân hàng. Vì vậy nội
dung triển khai không nên hứa rằng mọi ngân hàng đều có cùng schema, cùng OTP hoặc
cùng thời gian phản hồi. Trước khi đưa `Production` vào vận hành, đội kỹ thuật cần
thử đúng loại tài khoản, ngân hàng và gói dịch vụ mà doanh nghiệp đang dùng.

API thanh toán ngân hàng Pay2S cũng không tự quyết định nghiệp vụ của doanh nghiệp.
Nó không thay thế hệ thống đơn hàng, không tự biết khoản tiền nào được miễn đối 
soát và không làm cho webhook trở thành bằng chứng duy nhất. Một kiến trúc an toàn
luôn có log, retry có giới hạn, khóa chống trùng, màn hình kiểm tra và quy trình
xử lý khi trạng thái không xác định.

## Góc nhìn triển khai thực tế

Ở góc nhìn kiến trúc, nên tách ba lớp khi triển khai BankHub. Lớp giao tiếp chịu
trách nhiệm lấy token, gọi endpoint và chuẩn hóa lỗi; lớp dữ liệu lưu liên kết ngân
hàng, webhook, transaction và lịch sử xử lý; lớp nghiệp vụ quyết định ghép khoản
tiền vào đơn hàng, hóa đơn hoặc công nợ. Cách tách này giúp thay đổi cơ chế retry
hay phiên bản `SDK` mà không làm thay đổi quy tắc kế toán. Nó cũng giúp đội vận 
hành truy được một giao dịch từ mã đơn, qua bản ghi webhook, đến ID phía Pay2S và
tài khoản nhận tiền. Khi thiết kế ngay từ đầu, hãy thống nhất timezone, kiểu dữ 
liệu tiền tệ, quy tắc làm tròn và cách lưu nội dung chuyển khoản nguyên bản.

Một lỗi triển khai thường gặp là coi request thành công là trạng thái nghiệp vụ 
thành công. `HTTP 200` chỉ cho biết request được tiếp nhận theo hợp đồng của endpoint,
không nhất thiết có nghĩa tài khoản đã liên kết, giao dịch đã đối soát hay hóa đơn
đã phát hành. Mỗi trạng thái cần có nguồn xác minh phù hợp: session status cho luồng
Hosted Link, danh sách tài khoản cho liên kết, webhook cho dữ liệu chủ động gửi 
về và màn hình đối soát cho trường hợp không đủ dữ kiện. Với các tác vụ quan trọng,
lưu cả request ID, response rút gọn và thời gian xử lý để nhân viên có thể giải 
thích chênh lệch cho khách hàng.

Khi đưa vào `Production`, nên chạy theo một lộ trình có điểm kiểm soát. Trước hết
kiểm tra credential và schema ở `UAT` bằng dữ liệu giả; sau đó thử timeout, token
hết hạn, webhook gửi lại, payload thiếu trường tùy chọn và hai request đến đồng 
thời. Tiếp theo giới hạn quyền truy cập dashboard, bật cảnh báo lỗi, kiểm tra backup
và lập người chịu trách nhiệm khi tài khoản mất kết nối. Chỉ sau khi các tình huống
này có runbook mới chuyển sang tài khoản thật. Đây là nền tảng để API thanh toán
ngân hàng Pay2S phục vụ hoạt động ổn định trên hoadontudong.com.vn thay vì chỉ chạy
được một demo đẹp.

## Quy trình triển khai API thanh toán ngân hàng Pay2S

 1. Lấy `Access Key` và `Secret Key` tại Merchant Bankhub, không đưa khóa vào frontend.
 2. Gọi authorize và lưu `Bearer Token` theo thời hạn `expires_in`.
 3. Liên kết tài khoản thử nghiệm, xác nhận OTP và đọc lại danh sách.
 4. Lưu `user_bank_id`, không dùng số tài khoản thay cho ID bản ghi.
 5. Tạo webhook đúng loại giao dịch và xác thực webhook token.
 6. Lưu giao dịch bền vững, chống trùng trước khi cập nhật đơn hàng.
 7. Theo dõi Analytics, lịch sử webhook và đối soát định kỳ.
 8. Chỉ chuyển `Production` sau khi `UAT` đã được kiểm thử theo đúng mô hình.

## Câu hỏi thường gặp

### API thanh toán ngân hàng Pay2S có phải API hóa đơn điện tử không?

Không. Partner API và BankHub xử lý tài khoản ngân hàng, giao dịch, webhook và metrics.
API hóa đơn điện tử là nhóm riêng, có endpoint và cơ chế xác thực khác.

### BankHub có tự xác nhận đơn đã thanh toán không?

Không. BankHub cung cấp dữ liệu giao dịch; hệ thống đối tác phải khớp tài khoản,
số tiền, mã tham chiếu và chống trùng theo nghiệp vụ.

### Có cần dùng Hosted Link không?

Không bắt buộc. Hosted Link phù hợp khi muốn khách nhập và xác thực trên form Pay2S;
API trực tiếp phù hợp khi backend cần kiểm soát nhiều hơn.

### Webhook giao dịch và webhook Hosted Link có giống nhau không?

Không. Một loại báo giao dịch tiền vào hoặc ra, loại còn lại báo tiến trình và trạng
thái liên kết tài khoản.

### Nên bắt đầu từ `Production` hay `UAT`?

Nên bắt đầu từ `UAT`, thử đúng luồng liên kết, OTP, webhook, retry và đối soát rồi
mới cấu hình `Production`.

## Đọc tiếp trong cụm BankHub Pay2S

 * [xác thực Partner API Pay2S](https://hoadontudong.com.vn/xac-thuc-api-thanh-toan-ngan-hang-pay2s/)
 * [liên kết tài khoản ngân hàng Pay2S](https://hoadontudong.com.vn/lien-ket-tai-khoan-ngan-hang-pay2s-api/)
 * [Hosted Link và SDK BankHub](https://hoadontudong.com.vn/pay2s-bankhub-hosted-link-sdk/)
 * [webhook giao dịch ngân hàng](https://hoadontudong.com.vn/webhook-giao-dich-ngan-hang-pay2s/)
 * [Analytics API và nhật ký tích hợp](https://hoadontudong.com.vn/analytics-api-thanh-toan-ngan-hang-pay2s/)