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

API ngân hàng Pay2S: Webhook đối soát đơn hàng tự độ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.

API ngân hàng Pay2S kết hợp Webhook giúp backend nhận thông báo chuyển khoản và đối chiếu với đơn hàng. Để vận hành ổn định, hệ thống cần kiểm tra nguồn gửi, số tiền, tài khoản nhận và giao dịch đã xử lý.

Bài này hướng dẫn thiết kế receiver cho Webhook giao dịch Partner API. Nếu chưa cấu hình kết nối, hãy bắt đầu với hướng dẫn tích hợp Partner API Pay2S.

1. Luồng Webhook API ngân hàng Pay2S

Sau khi đăng ký Webhook, Pay2S gửi HTTP POST đến URL của bạn khi có giao dịch phù hợp cấu hình. Backend tiếp nhận, xác thực, ghi nhận rồi xử lý nghiệp vụ.

Luồng đề xuất: nhận giao dịch → xác thực → lưu bền vững → đối chiếu → cập nhật đơn. Webhook giao dịch khác IPN thanh toán và Webhook sự kiện Hosted Link; không dùng chung giả định về xác thực hoặc cấu trúc phản hồi. Xem tài liệu Webhook Partner API.

2. Xác thực trước khi đọc nghiệp vụ

Request giao dịch có các header:

Content-Type: application/json
Authorization: Bearer WEBHOOK_TOKEN

So sánh với token của cấu hình Webhook tương ứng phía máy chủ. Không dùng Access Token gọi Partner API thay thế. Từ chối request sai token trước khi ghi nhận thanh toán.

Receiver nên kiểm tra JSON và mảng transactions, giới hạn kích thước request và ghi log có che thông tin nhạy cảm. Không xác nhận thanh toán chỉ dựa vào thông báo do trình duyệt gửi lên.

3. Đọc đúng dữ liệu giao dịch

Payload dưới đây là dữ liệu minh họa rút gọn:

{
  "transactions": [{
    "id": 10001,
    "gateway": "ACB",
    "accountNumber": "P2S99999999",
    "content": "THANHTOAN DH10001",
    "transferType": "IN",
    "transferAmount": 250000
  }]
}

Duyệt từng phần tử trong mảng. transferAmount là số tiền giao dịch, không phải số dư hiện tại. paymentCode và extraData có thể chỉ xuất hiện khi đủ điều kiện cấu hình; receiver không nên bắt buộc mọi giao dịch phải có các trường này.

4. Đối chiếu giao dịch với đơn hàng

Giả sử đơn DH10001 cần thanh toán 250.000 đồng. Quy tắc đề xuất trước khi đánh dấu đã thanh toán:

  1. Loại giao dịch là IN.
  2. Tài khoản nhận khớp cấu hình của đơn, có xử lý đúng trường hợp tài khoản ảo.
  3. Mã đơn khớp định dạng đã thống nhất.
  4. Số tiền khớp chính sách thanh toán.
  5. Giao dịch chưa được gắn cho đơn khác.

Chuyển thiếu, thừa hoặc sai mã nên vào hàng chờ kiểm tra theo quy trình cửa hàng. Tách trạng thái “đã nhận giao dịch” và “đã xác nhận đơn” để dễ truy vết.

Đọc thêm hướng dẫn truy vấn giao dịch Pay2S khi xây dựng công cụ kiểm tra chênh lệch.

5. Chống trùng và phản hồi thành công

Đặt khóa duy nhất theo ID giao dịch trong phạm vi dữ liệu phù hợp. Ghi nhận giao dịch và cập nhật đơn bằng thao tác cơ sở dữ liệu có tính nguyên tử; việc gửi lại cùng payload không được cộng tiền lần nữa.

Chỉ sau khi đã lưu thành công hoặc đưa vào hàng đợi bền vững, trả HTTP 200 cùng JSON:

{"success": true}

Nếu mất dữ liệu trước khi ACK, việc trả thành công quá sớm có thể khiến backend bỏ sót giao dịch. Khi phát sinh lỗi, đối chiếu lịch sử tại GET /v1/webhooks/history. Luồng gửi lại theo tài liệu hiện tại là POST /v1/webhooks/history/{history_id}/resend.

Trước vận hành, thử payload nhiều giao dịch, token sai, gửi trùng và lỗi lưu dữ liệu. Theo dõi riêng giao dịch chờ đối chiếu để nhân sự xử lý kịp thời.

Logo Pay2S by Web2M

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

Nhận Webhook là có thể xác nhận đơn ngay không?

Cần xác thực và hoàn thành quy tắc đối chiếu. Nhận thông báo và xác nhận thanh toán là hai bước riêng.

Webhook có tự phát hành hóa đơn cho mọi giao dịch không?

Không nên suy ra như vậy. Phần hóa đơn cần cấu hình và điều kiện riêng; tham khảo tài liệu hóa đơn điện tử Pay2S trước khi nối thêm nghiệp vụ.

Triển khai API ngân hàng Pay2S: bắt đầu với một tài khoản và bộ đơn thử, xác minh đối soát cùng chống trùng, sau đó mở rộng sang quy trình bán hàng thực tế.

Leave your comment

Tham khảo thêm