Khách hàng đã chuyển khoản nhưng đơn hàng trên website vẫn hiển thị "Chờ thanh toán". Nhân viên phải mở ứng dụng ngân hàng, kiểm tra giao dịch rồi cập nhật thủ công. Đơn càng nhiều, quy trình này càng dễ chậm và nhầm lẫn.
Webhook là gì? Đây là cơ chế để một hệ thống tự động gửi thông báo đến hệ thống khác khi có sự kiện xảy ra. Với payOS, webhook giúp website nhận kết quả thanh toán và tự động cập nhật đơn hàng. Bài viết này giải thích cách hoạt động, cách xác thực và những lưu ý khi tích hợp.
Webhook là gì?
Webhook là cơ chế tự động gửi dữ liệu từ hệ thống này đến một URL của hệ thống khác khi có sự kiện xảy ra, thường qua yêu cầu HTTP POST. Ứng dụng nhận dữ liệu gần như ngay lập tức mà không cần gọi API liên tục để hỏi "có gì mới không?".
Ví dụ, khi tích hợp cổng thanh toán payOS, website của bạn cần chuẩn bị một địa chỉ nhận webhook. Khi khách thanh toán thành công, payOS gửi dữ liệu giao dịch đến địa chỉ này. Website dùng dữ liệu đó để kiểm tra và xử lý đơn hàng.
Một kết nối webhook thường gồm ba thành phần:
- Sự kiện: Thay đổi cần thông báo, chẳng hạn một đơn hàng được thanh toán.
- Endpoint (webhook URL): Địa chỉ của hệ thống tiếp nhận.
- Payload: Nội dung dữ liệu gửi kèm trong yêu cầu.
Bạn có thể hình dung webhook giống thông báo biến động số dư. Điểm khác là bên nhận là phần mềm, nên dữ liệu có thể kích hoạt xử lý tự động.
Webhook hoạt động như thế nào?
Webhook hoạt động qua ba bước: đăng ký địa chỉ nhận, gửi dữ liệu khi có sự kiện, rồi xác thực và xử lý tại hệ thống tiếp nhận.
Bước 1: Đăng ký webhook URL
Trước tiên, website hoặc phần mềm cần có một endpoint nhận dữ liệu. Ví dụ:
https://your-server.com/webhook-urlĐây là địa chỉ minh họa trên hệ thống của bạn, không phải endpoint của payOS.
Sau đó, bạn khai báo URL này cho kênh thanh toán trên payOS. Theo tài liệu, payOS cung cấp API confirm-webhook để kiểm tra và thêm hoặc cập nhật webhook URL. Khi xác nhận, payOS gửi một dữ liệu mẫu đến URL để kiểm tra webhook có hoạt động hay không.
Endpoint nên dùng HTTPS và truy cập được từ bên ngoài. Hãy dùng đúng URL cho từng môi trường để tránh nhầm giữa thử nghiệm và vận hành.
Bước 2: payOS gửi dữ liệu khi có sự kiện
Khi có giao dịch thanh toán, payOS gửi một yêu cầu đến webhook URL. Theo tài liệu, nội dung gồm các trường chính:
codevàdesc: mã và mô tả kết quả.success: trạng thái thành công hay không.data: thông tin giao dịch nhưorderCode,amount,description,reference,transactionDateTime,paymentLinkId.signature: chữ ký để kiểm tra tính toàn vẹn dữ liệu.
Website có thể dùng những thông tin này để:
- Xác định giao dịch cần xử lý.
- Tìm đơn hàng tương ứng qua
orderCode. - Kiểm tra số tiền và trạng thái.
- Ghi nhận kết quả xử lý.
Thời điểm nhận thực tế còn phụ thuộc vào kết nối mạng và tình trạng của các hệ thống liên quan.
Bước 3: Xác thực, ghi nhận và phản hồi
Khi nhận webhook, website cần xác thực dữ liệu trước khi cập nhật đơn. Một luồng xử lý phù hợp gồm:
- Kiểm tra
signaturebằngchecksum keycủa kênh thanh toán. - Kiểm tra cấu trúc và các trường bắt buộc.
- Ghi nhận giao dịch để tránh xử lý trùng.
- Đối chiếu với đơn hàng và quy tắc thanh toán.
- Cập nhật trạng thái, rồi thực hiện các tác vụ liên quan.
Theo tài liệu payOS, endpoint cần phản hồi mã trạng thái 2XX để xác nhận đã nhận webhook. Với tác vụ nặng như gửi email hoặc đồng bộ phần mềm khác, bạn có thể đưa vào hàng đợi xử lý nền.
Cần phân biệt "đã nhận webhook" với "đã xác nhận đơn hàng". Dữ liệu vẫn phải qua các điều kiện nghiệp vụ trước khi đơn được đánh dấu đã thanh toán.
Webhook khác gì với gọi API và polling?
Webhook và API thường dùng cùng nhau. Khác biệt chính nằm ở bên chủ động gửi yêu cầu và thời điểm trao đổi dữ liệu.
Nếu website kiểm tra mỗi phút, một giao dịch phát sinh ngay sau lần kiểm tra phải chờ đến lượt sau. Webhook giúp nhận thông báo theo sự kiện và giảm số lần gọi không cần thiết.
Khi nào dùng webhook, khi nào dùng API?
- Dùng webhook để nhận thay đổi và xử lý sớm, ví dụ cập nhật đơn sau khi khách thanh toán.
- Dùng API để chủ động tra cứu, lấy thêm thông tin hoặc đối soát lại.
Không nên xem webhook là lý do để bỏ hoàn toàn bước kiểm tra và đối soát.
Ứng dụng thực tế của webhook trong thu hộ và chi hộ
Thu hộ: tự động xác nhận thanh toán đơn hàng
Với thu hộ, webhook là cầu nối giữa kết quả thanh toán và hệ thống bán hàng. Giả sử đơn DH1028 có giá trị 350.000 đồng và khách thanh toán qua link do payOS tạo. Khi nhận webhook, website đối chiếu giao dịch với đơn.
Các điều kiện nên kiểm tra:
orderCodecó khớp đơn hàng không?- Số tiền và trạng thái giao dịch có phù hợp không?
- Giao dịch đã được ghi nhận trước đó chưa?
- Đơn còn đủ điều kiện để tự động xác nhận không?
Nếu thỏa quy tắc đã thiết lập, website chuyển đơn sang "Đã thanh toán". Sau đó, hệ thống có thể gửi xác nhận, chuyển bộ phận giao hàng hoặc kích hoạt dịch vụ.
payOS gửi thông báo thanh toán qua webhook. Việc cập nhật đơn hàng do website, phần mềm hoặc plugin đã tích hợp thực hiện. Với trường hợp thiếu hoặc thừa tiền, nên có luồng kiểm tra riêng thay vì tự động xác nhận.
Chi hộ: theo dõi và đối soát lệnh chi
Với chi hộ (payout), doanh nghiệp tạo lệnh chi qua API, ví dụ để trả lương, hoàn tiền hoặc thanh toán cho đối tác. Theo tài liệu, API tạo lệnh chi yêu cầu x-idempotency-key để bảo đảm tính duy nhất của yêu cầu. Bạn cũng có thể lấy danh sách và chi tiết lệnh chi để theo dõi trạng thái.
Vì vậy, với chi hộ, hãy chú ý hai điểm:
- Dùng khóa idempotency và
referenceIdriêng cho từng lệnh để tránh chi trùng. - Kiểm tra trạng thái lệnh chi qua API tra cứu khi cần đối soát.
Chữ ký của API payouts khác với chữ ký của payment-requests. Hãy đọc đúng phần tài liệu cho từng luồng và không dùng lẫn cách tạo chữ ký.
Đồng bộ dữ liệu giữa các hệ thống
Sau khi xác minh dữ liệu từ payOS, phần mềm của bạn có thể kích hoạt các việc sau:
- Website bán hàng: Cập nhật trạng thái thanh toán.
- Phần mềm kế toán/quản lý: Ghi nhận giao dịch và liên kết với đơn.
- Hệ thống thông báo: Gửi xác nhận cho khách hoặc báo nội bộ.
- Hệ thống dịch vụ: Kích hoạt quyền sử dụng khi đủ điều kiện.
- Báo cáo vận hành: Tổng hợp các giao dịch đã xử lý.
Những hành động này phụ thuộc vào cách triển khai của bên tích hợp. Webhook là đầu vào dữ liệu, còn quy trình tự động cần thiết kế phù hợp với hoạt động kinh doanh.
Các bước thiết lập và kiểm tra webhook cơ bản
Để tích hợp webhook payOS, bạn cần chuẩn bị endpoint, cấu hình theo tài liệu và kiểm thử toàn bộ luồng trước khi vận hành.
Chuẩn bị và cấu hình
- Tạo kênh thanh toán trên payOS: Lấy
Client ID,API KeyvàChecksum Key. - Xây dựng endpoint HTTPS: Chấp nhận yêu cầu POST và phản hồi mã 2XX theo tài liệu.
- Đăng ký webhook URL: Qua
my.payos.vnhoặc APIconfirm-webhook, nếu phù hợp với hệ thống của bạn. - Thiết lập xác thực: Lưu
Checksum Keyở phía máy chủ. - Chuẩn bị lưu trữ và log: Ghi nhận dữ liệu cần thiết để kiểm tra và xử lý lỗi.
Không đưa khóa bí mật vào mã giao diện hoặc kho mã công khai. Payos cũng cung cấp SDK cho một số ngôn ngữ, trong đó có hàm xác minh webhook, giúp giảm sai sót khi tự viết.
Các tình huống nên kiểm thử
Ngoài trạng thái đơn, hãy kiểm tra cả mã phản hồi HTTP và thời gian phản hồi. Không trả về thành công khi dữ liệu chưa được ghi nhận an toàn.
Lưu ý để xử lý webhook an toàn và tin cậy
Tích hợp webhook không chỉ là tạo một URL. Hệ thống còn phải kiểm soát nguồn gửi, tránh xử lý lặp và có phương án đối soát.
Xác thực signature trước khi xử lý
Endpoint nhận webhook có thể bị truy cập từ bên ngoài. Một yêu cầu trông giống thông báo thanh toán chưa chắc là hợp lệ.
Theo tài liệu payOS, signature được tạo bằng thuật toán HMAC_SHA256 với Checksum Key. Dữ liệu tạo chữ ký có dạng key1=value1&key2=value2... và các key được sắp xếp theo thứ tự alphabet. Với webhook thanh toán, bạn kiểm tra chữ ký trên đối tượng data.
Hãy làm đúng theo mẫu mã trong tài liệu hoặc dùng hàm xác minh của SDK. Không tự suy đoán thuật toán từ hướng dẫn của nền tảng khác.
Sau khi xác thực, vẫn cần kiểm tra điều kiện nghiệp vụ. Chữ ký hợp lệ không đồng nghĩa giao dịch chắc chắn khớp với một đơn cụ thể.
Chống xử lý trùng (idempotency)
Một sự kiện có thể được gửi hoặc tiếp nhận nhiều lần. Bên tích hợp cần bảo đảm xử lý lại không gây xác nhận hoặc cấp dịch vụ nhiều lần. Nguyên tắc này gọi là idempotency.
Bạn nên:
- Lưu mã nhận diện giao dịch như
orderCode,referencehoặcpaymentLinkId. - Áp dụng ràng buộc duy nhất trong cơ sở dữ liệu.
- Kiểm soát trường hợp nhiều yêu cầu đến đồng thời.
- Kiểm tra trạng thái đơn trước khi thực hiện hành động.
- Theo dõi riêng trạng thái "đã nhận" và "đã xử lý".
Không nên chống trùng chỉ bằng số tiền và nội dung chuyển khoản, vì nhiều giao dịch có thể giống nhau.
Đối soát khi thông báo đến chậm hoặc bị bỏ lỡ
Mạng gián đoạn, endpoint ngừng hoạt động hoặc lỗi nội bộ đều có thể làm gián đoạn luồng cập nhật. Vì vậy, doanh nghiệp nên:
- Ghi lại thời điểm nhận và kết quả xử lý.
- Theo dõi lỗi tiếp nhận và lỗi cập nhật đơn.
- Cảnh báo khi có giao dịch chưa ghép được với đơn.
- Đối chiếu định kỳ với dữ liệu tra cứu từ payOS.
- Cho phép xử lý lại theo cùng quy tắc xác thực và chống trùng.
Chính sách gửi lại và thời gian chờ cần được kiểm tra trong tài liệu payOS tại thời điểm triển khai.
Kết luận
Webhook là gì? Đó là cơ chế giúp hệ thống chủ động gửi dữ liệu khi có sự kiện, hỗ trợ tự động hóa quy trình và giảm việc gọi kiểm tra liên tục.
Trong luồng thu hộ qua payOS, webhook cung cấp kết quả thanh toán để website kiểm tra, đối chiếu và cập nhật đơn hàng. Khi kết hợp xác thực signature, chống xử lý trùng và đối soát, doanh nghiệp giảm thao tác thủ công và xử lý thanh toán nhất quán hơn.
Nếu bạn đang cần tự động hóa thanh toán cho website hoặc ứng dụng, hãy xem tài liệu tích hợp webhook tại payOS và chọn phương án phù hợp với hệ thống của mình.
Để được hướng dẫn đăng ký và nhận ưu đãi, khách hàng vui lòng liên hệ
Cổng thanh toán miễn phí payOS
Hotline: 1900 8144
Website: https://payos.vn/
Email: cskh@payos.vn
Facebook: https://www.facebook.com/payosvn
Câu hỏi thường gặp (FAQ)
Webhook là gì và dùng để làm gì?
Webhook là cơ chế tự động gửi dữ liệu đến URL của hệ thống khác khi có sự kiện. Trong thanh toán, nó giúp website nhận kết quả giao dịch để cập nhật đơn hàng mà không cần kiểm tra thủ công.
Webhook khác API ở điểm nào?
Với API, hệ thống của bạn chủ động gửi yêu cầu để lấy dữ liệu. Với webhook, hệ thống phát sinh sự kiện chủ động gửi dữ liệu cho bạn. Hai cơ chế thường được dùng song song.
Làm sao biết webhook từ payOS là hợp lệ?
Hãy kiểm tra trường signature bằng HMAC_SHA256 và Checksum Key của kênh thanh toán, theo hướng dẫn trong tài liệu payOS. Nếu chữ ký không khớp, không nên xử lý dữ liệu.
Endpoint cần phản hồi như thế nào khi nhận webhook?
Theo tài liệu payOS, endpoint cần phản hồi mã trạng thái 2XX để xác nhận đã nhận webhook. Chỉ nên trả mã này khi dữ liệu đã được ghi nhận an toàn.
Có cần đối soát nếu đã dùng webhook không?
Có. Thông báo có thể đến chậm hoặc bị bỏ lỡ do lỗi mạng hay lỗi hệ thống. Đối soát định kỳ giúp phát hiện các giao dịch chưa khớp.
