Đăng ký
Hướng dẫn

Webhook OAuth Pay2S: tạo, xác minh chữ ký và chống trùng

API ngân hàng Pay2S: Webhook gửi giao dịch đến máy chủ để đối soát đơn hàng và chống trùng.

Webhook OAuth Pay2S dùng để làm gì?

Webhook OAuth Pay2S giúp phần mềm nhận thông báo giao dịch tại máy chủ sau khi khách hàng cấp quyền và chọn ngân hàng. Thay vì liên tục quét dữ liệu, backend tiếp nhận request, xác minh chữ ký rồi cập nhật đơn hàng hoặc quy trình đối soát.

Bài viết này nối tiếp hướng dẫn OAuth Pay2S cho ứng dụng và bài quản lý Access Token Pay2S. Nội dung chỉ nói về thông báo dữ liệu; OAuth hiện chưa cấp quyền chuyển tiền, tạo thanh toán hay xuất hóa đơn.

Webhook OAuth Pay2S gửi giao dịch đến máy chủ để đối soát đơn hàng
hoadontudong.com.vn
Mô hình nhận webhook Pay2S và đối soát giao dịch

Điều kiện trước khi tạo webhook OAuth Pay2S

  • Ứng dụng đã hoàn tất luồng Authorization Code + PKCE và có Access Token hợp lệ.
  • Người dùng đã cấp scope webhooks:write cùng quyền ngân hàng cần dùng.
  • Đã có bank_id thuộc kết nối của người dùng.
  • Receiver là URL HTTPS công khai; không dùng địa chỉ IP nội bộ và không phụ thuộc redirect.
  • Mỗi lần tạo webhook dùng request_key riêng để chống tạo trùng.

Không cần khai báo Webhook URL ngay lúc đăng ký ứng dụng. Dev truyền URL khi gọi API tạo webhook, sau khi người dùng cấp quyền và chọn ngân hàng.

Các thao tác và scope cần dùng

Thao tác Method Scope
Danh sách webhook GET webhooks:read
Tạo webhook POST webhooks:write
Bật hoặc tắt PATCH webhooks:write
Xóa webhook DELETE webhooks:delete

Mỗi request API gửi Authorization: Bearer ACCESS_TOKEN. Nếu token hết hạn, xử lý theo bài refresh token Pay2S; không retry liên tục khi lỗi quyền hoặc kết nối đã bị thu hồi.

Quy trình tạo và tiếp nhận webhook

  1. Backend lấy danh sách ngân hàng được cấp quyền và chọn bank_id.
  2. Gọi API tạo webhook với URL HTTPS, ngân hàng, hướng giao dịch và request_key duy nhất.
  3. Lưu signing_secret được trả về ở lần tạo đầu tiên trong kho bí mật phía server.
  4. Receiver nhận raw body, kiểm tra chữ ký trước khi parse hoặc xử lý dữ liệu.
  5. Kiểm tra khóa định danh sự kiện để chống trùng; ghi nhận event đã xử lý.
  6. Trả HTTP 2xx ngay khi đã tiếp nhận hợp lệ, sau đó đẩy phần xử lý nặng sang hàng đợi.
Lưu ý quan trọng: Không ghi signing_secret, Access Token hoặc Client Secret vào log. Không xác minh chữ ký trên body đã bị parse rồi serialize lại; hãy giữ nguyên raw body.

Checklist receiver trước khi lên production

  • ✅ Chỉ nhận HTTPS và chặn địa chỉ nội bộ.
  • ✅ Xác minh chữ ký trước khi tin request.
  • ✅ Chống trùng theo event ID hoặc khóa giao dịch phù hợp.
  • ✅ ACK 2xx nhanh, không để timeout vì xử lý đồng bộ quá lâu.
  • ✅ Theo dõi retry, lỗi 502 và tình trạng receiver.
  • ✅ Khi thu hồi OAuth, dừng webhook liên quan và đánh dấu kết nối vô hiệu.
Logo Pay2S trong bài hướng dẫn Webhook OAuth cho ứng dụng
hoadontudong.com.vn
Branding Pay2S cho bộ tài liệu tích hợp OAuth

Câu hỏi thường gặp về Webhook OAuth Pay2S

Có cần khai báo URL webhook khi tạo app không?

Không. URL được truyền khi gọi API tạo webhook sau khi người dùng đã cấp quyền webhook và chọn ngân hàng.

Thu hồi kết nối có dừng webhook không?

Có. Thu hồi kết nối hoặc khóa ứng dụng sẽ dừng chuyển tiếp webhook liên quan.

Có nên xử lý đơn hàng ngay trong request webhook không?

Không nên nếu tác vụ mất thời gian. Hãy xác minh, chống trùng, lưu event, trả 2xx rồi xử lý bất đồng bộ.

Hoàn thiện kết nối OAuth Pay2S

Đọc luồng OAuth, quản lý token và webhook như một chuỗi vận hành thống nhất.

Xem tài liệu Webhook Pay2S

Leave your comment

Tham khảo thêm