Một lượt checkout crypto phát ra những sự kiện nào?

InfraIO Pay bắn một webhook cho mỗi lần chuyển trạng thái. Cỗ máy trạng thái này được thiết kế nhỏ gọn có chủ đích, để bạn có thể gắn việc hoàn tất đơn hàng vào đúng một sự kiện và bỏ qua phần còn lại.

  • payment.pending, người mua đã phát giao dịch; số lần xác nhận vẫn đang tích lũy.
  • payment.confirmed, giao dịch đã đạt ngưỡng xác nhận của mạng.
  • payment.settled, tiền đã được sweep về ví quyết toán của bạn. Hoàn tất đơn hàng ở đây.
  • session.expired, cửa sổ checkout đã đóng mà không có thanh toán. Không bao giờ bị tính phí.

Bạn nên hoàn tất đơn hàng ở sự kiện nào?

Hãy hoàn tất đơn hàng ở payment.settled. Một giao dịch pending vẫn có thể không được xác nhận, và ngưỡng xác nhận khác nhau theo từng mạng, vì vậy nếu coi bất kỳ trạng thái sớm hơn là cuối cùng, bạn có rủi ro giao hàng cho một khoản thanh toán không bao giờ hoàn tất. Quyết toán là thời điểm mà số tiền đó thuộc về bạn một cách không thể đảo ngược.

Nếu bạn cần hiển thị tiến trình cho người mua, bạn có thể hiện pending và confirmed trên UI, nhưng hãy giữ hành động không thể đảo ngược (giao hàng, cấp quyền truy cập, mint) gắn với settled.

Làm sao để xác minh một webhook là thật?

Mỗi webhook đều được ký bằng secret của endpoint của bạn. Tính lại HMAC trên toàn bộ raw request body và so sánh nó theo constant-time với header chữ ký; từ chối bất cứ thứ gì không khớp. Nếu bạn mới làm quen với HMAC, tài liệu SubtleCrypto.sign của MDN là một nguồn nhập môn tốt, và hướng dẫn best-practice về webhook của Stripe bao quát tốt khía cạnh vận hành.

Xác minh trước khi bạn parse hoặc xử lý. Một request không có chữ ký hoặc ký sai không bao giờ nên chạm tới business logic của bạn.

Làm sao để việc gửi lại (retry) an toàn?

Webhook được gửi theo cơ chế at-least-once, nên cùng một sự kiện có thể đến nhiều hơn một lần sau một trục trặc mạng. Mỗi sự kiện mang một idempotency key; hãy ghi lại các key bạn đã xử lý và bỏ qua (no-op) với các lần lặp lại. Phản hồi 2xx nhanh và xử lý phần việc nặng một cách bất đồng bộ để bên gửi không bị timeout và retry không cần thiết. InfraIO lưu một delivery log với khả năng replay một cú nhấp cho những lúc bạn cần xử lý lại một cách chủ động.