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 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
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 sẽ tách riêng hai luồng này.
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
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 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
- Lấy
Access KeyvàSecret Keytại Merchant Bankhub, không đưa khóa vào frontend. - Gọi authorize và lưu
Bearer Tokentheo thời hạnexpires_in. - Liên kết tài khoản thử nghiệm, xác nhận OTP và đọc lại danh sách.
- Lưu
user_bank_id, không dùng số tài khoản thay cho ID bản ghi. - Tạo webhook đúng loại giao dịch và xác thực webhook token.
- Lưu giao dịch bền vững, chống trùng trước khi cập nhật đơn hàng.
- Theo dõi Analytics, lịch sử webhook và đối soát định kỳ.
- Chỉ chuyển
Productionsau khiUATđã đượ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.
