Tích hợp Webhook ngân hàng qua Tingee Open API
Webhook ngân hàng là giải pháp giúp website hoặc phần mềm bán hàng tự động xác nhận thanh toán ngay khi tiền về tài khoản, không cần kiểm tra sao kê thủ công. Bài viết trình bày khái niệm, cách hoạt động, lợi ích, quy trình tích hợp, bảo mật, xử lý lỗi và cách thiết lập thủ công trên Tingee.
Webhook ngân hàng là gì?
Webhook là cơ chế cho phép một hệ thống tự động gửi dữ liệu đến hệ thống khác ngay khi có sự kiện phát sinh, thay vì để bên nhận hỏi liên tục (polling). Webhook ngân hàng áp dụng cơ chế này cho biến động số dư: Mỗi khi tài khoản có giao dịch tiền vào hoặc tiền ra, hệ thống trung gian gửi yêu cầu HTTP POST đến URL của doanh nghiệp. Phần lớn ngân hàng không gửi trực tiếp cho doanh nghiệp nhỏ, nên doanh nghiệp dùng dịch vụ của bên thứ ba như Tingee, SePay, Casso hoặc Open API của ngân hàng.
Webhook ngân hàng hoạt động như thế nào?
Luồng xử lý 5 bước
- Tạo đơn hàng: Website tạo mã VietQR kèm số tiền và nội dung chuyển khoản chứa mã đơn, ví dụ DH12345.
- Khách chuyển khoản: Khách quét mã bằng ứng dụng ngân hàng.
- Ngân hàng ghi nhận: Tiền vào tài khoản, phát sinh biến động số dư.
- Nhà cung cấp gửi webhook: Hệ thống trung gian gửi yêu cầu POST đến URL của doanh nghiệp.
- Hệ thống xử lý: Máy chủ đối chiếu mã đơn và số tiền, cập nhật trạng thái, trả mã phản hồi thành công.
Dữ liệu webhook
Dữ liệu thường ở định dạng JSON, gồm mã giao dịch (dùng để chống xử lý trùng), thời gian, số tài khoản, số tiền, loại giao dịch và nội dung chuyển khoản (dùng để xác định đơn hàng). Với ngân hàng chỉ hỗ trợ xác thực qua tài khoản ảo (VA), mỗi đơn hàng được cấp một số tài khoản riêng để khớp lệnh chính xác hơn.
Lợi ích của webhook ngân hàng
Lợi ích chung
- Tự động đối soát: Loại bỏ việc kiểm tra sao kê thủ công, giảm sai sót.
- Xác nhận gần như tức thì: Đơn hàng được xử lý ngay sau khi khách thanh toán.
- Tiền về trực tiếp tài khoản doanh nghiệp: Khác với cổng thanh toán trung gian, webhook ngân hàng thường không thay đổi dòng tiền.
Tính năng webhook Tingee
Webhook Tingee (IPN – Instant Payment Notification) là cơ chế Tingee chủ động gửi thông báo đến máy chủ đối tác khi có biến động giao dịch:
- Sự kiện: PAYMENT_SUCCESS (giao dịch QR hoặc tài khoản ảo), DEEPLINK_RETURN (thanh toán qua Deep Link), DIRECT_DEBIT_RESULT (trích nợ trực tiếp).
- Chữ ký: header x-signature tính bằng HMAC-SHA512 với secret token.
- Gửi lại: tự động gửi lại khi endpoint không trả HTTP 200 hoặc quá thời gian chờ; số lần và khoảng chờ có thể cấu hình.
Ứng dụng webhook Tingee
- Xác nhận đơn hàng tự động: Cập nhật trạng thái “đã thanh toán” sau khi khách quét VietQR, thời gian xác nhận khoảng 5 – 15 giây.
- Xử lý chênh lệch số tiền: Chuyển thiếu thì đơn giữ trạng thái chờ xử lý, chuyển thừa thì đơn được đánh dấu đã thanh toán và ghi chú phần chênh lệch.
Hướng dẫn tích hợp webhook ngân hàng trong 6 bước
- Chọn nhà cung cấp: So sánh ngân hàng hỗ trợ, tốc độ, mức phí, tài liệu và sandbox.
- Liên kết tài khoản: Khai báo ngân hàng, số tài khoản và xác thực qua internet banking hoặc OAuth.
- Chuẩn bị endpoint: Tạo URL HTTPS công khai, ví dụ https://ten-mien-cua-ban.com/api/webhook.
- Đăng ký webhook: Nhập URL, chọn tài khoản, loại sự kiện và kiểu chứng thực.
- Lập trình xử lý: Xác thực nguồn gọi, đọc mã đơn, so khớp số tiền, cập nhật đơn và trả HTTP 200.
- Kiểm thử: Dùng sandbox, sau đó chuyển khoản từ 5.000 đến 10.000 đồng bằng tài khoản thật.
Bảo mật webhook ngân hàng
Xác thực nguồn gọi
Cần kiểm tra API Key, secure token hoặc chữ ký trong header của mọi yêu cầu. Với chữ ký, máy chủ tính lại HMAC từ nội dung và khóa bí mật rồi so sánh; Tingee dùng HMAC-SHA512 với header x-signature. Endpoint chỉ nhận yêu cầu qua HTTPS.
Kiểm tra dữ liệu và bảo vệ khóa
Luôn so sánh số tiền nhận được với giá trị đơn hàng. Khóa bí mật của webhook ngân hàng cần lưu trong biến môi trường, không đưa vào mã nguồn công khai.
Xử lý lỗi khi dùng webhook ngân hàng
Gửi lại và thời gian chờ
Hệ thống gửi webhook thường tự động gửi lại khi gặp lỗi: Đối với Tingee Open API thử lại tối đa 5 lần, SePay thử lại tối đa 7 lần, Casso tối đa 17 lần.
Chống trùng lặp và đối soát định kỳ
Một giao dịch có thể được gửi nhiều lần, vì vậy máy chủ cần lưu mã giao dịch đã xử lý và bỏ qua yêu cầu trùng. Ngoài webhook ngân hàng, nên gọi API lấy danh sách giao dịch theo khoảng thời gian để phát hiện giao dịch bị bỏ sót.
Thiết lập webhook thủ công – Tingee Developer
Thiết lập thủ công webhook trên Tingee gồm 4 bước:
Bước 1: Lấy Client ID và Secret Token
Truy cập Tingee BaaS Portal, vào mục API Credentials, nhấn Tạo mới, điền tên gợi nhớ, mô tả và chọn quyền truy cập (Cổng thanh toán, QR, Bank Link, Direct Debit hoặc Chọn tất cả). Nhấn Tạo API Credentials, sau đó sao chép Client ID và Secret Token.
Bước 2: Tạo endpoint webhook
Tại mục Webhook, nhấn Tạo mới và điền:
- Tên endpoint và URL webhook endpoint; có thể bấm Kiểm tra kết nối.
- Phạm vi sự kiện: Ví dụ QR Code, áp dụng cho Tất cả, Số tài khoản ảo hoặc Cửa hàng; có thể thiết lập Danh sách đen.
- Cấu hình gọi lại (Retry): Timeout 5 – 10 giây, 1 – 5 lần gửi lại, khoảng chờ 2 – 3600 giây.
- Kiểu chứng thực: None, API Key hoặc API Credentials.
Bước 3: Xác thực chữ ký và phản hồi
Để xác thực yêu cầu webhook ngân hàng, tính x-signature = HMAC_SHA512(x-request-timestamp + “:” + requestBody, secretToken), trong đó timestamp có định dạng yyyyMMddHHmmssSSS (UTC+7) và requestBody là chuỗi JSON đã minify. Nếu chữ ký không khớp, bỏ qua yêu cầu. Kiểm tra transactionId hoặc orderId để tránh xử lý trùng, rồi trả HTTP 200.
Bước 4: Theo dõi nhật ký webhook
Vào Sử dụng (Usage), tab Lịch sử webhook để xem trạng thái gửi, số lần retry, mã HTTP và nội dung Request/Response của từng sự kiện.
Câu hỏi thường gặp
Webhook có an toàn không?
Có, khi áp dụng HTTPS, xác thực chữ ký, kiểm tra số tiền và chống xử lý trùng.
Webhook khác gì cổng thanh toán?
Cổng thanh toán thu tiền rồi chuyển lại cho doanh nghiệp, còn webhook chỉ thông báo khi tiền đã vào tài khoản của doanh nghiệp.
Webhook ngân hàng giúp tự động hóa xác nhận thanh toán, nhanh và chính xác hơn. Doanh nghiệp cần chọn nhà cung cấp phù hợp, bảo mật endpoint, chống xử lý trùng, đối soát định kỳ và kiểm thử trên sandbox trước khi vận hành thật. Nếu Quý doanh nghiệp đang quan tâm giới giải pháp này, liên hệ ngay Tingee để nhận tư vấn từ chuyên gia.
