Webhook thanh toán crypto: cách xử lý id và status
Hướng dẫn webhook thanh toán crypto: nhận trạng thái cuối qua POST với id và status, kiểm tra header x-api-key và cập nhật đơn hàng an toàn.
Webhook thanh toán crypto báo cho backend của bạn trạng thái cuối của một thanh toán. Ở Qvard, đó là một POST chứa mã đơn hàng và trạng thái, nên logic đơn hàng cập nhật mà không cần hỏi API liên tục.
Webhook gửi những gì
Qvard gọi URL webhook của bạn bằng một yêu cầu POST. Nội dung gồm id mà bạn đã gửi khi tạo thanh toán và trạng thái, ví dụ paid. Yêu cầu mang token x-api-key của bạn trong header.
Kiểm tra header x-api-key
Trước khi tin vào thông điệp, so sánh header x-api-key với token trong tài khoản của bạn. Từ chối các yêu cầu không có header này, để không ai có thể đánh dấu đơn hàng đã thanh toán chỉ bằng cách gọi trực tiếp endpoint của bạn.
x-api-key: sk_live_…
{ "id": "order_1024", "status": "paid" }Cập nhật đơn hàng theo id
Tìm đơn hàng theo id trong nội dung và thay đổi trạng thái theo status. Chỉ đánh dấu đơn hàng đã thanh toán khi status là paid, và bỏ qua các trạng thái mà hệ thống của bạn không xử lý.
Làm cho bộ xử lý an toàn khi lặp lại
Cùng một webhook có thể đến nhiều hơn một lần. Lưu id và status đã xử lý và không làm gì nếu sự kiện đó đã được xử lý. Phản hồi mã thành công sau khi thay đổi đã được lưu.
Phản hồi nhanh, đưa việc chậm vào hàng đợi
Xác nhận webhook ngay khi đơn hàng được lưu. Gửi email, hóa đơn và các lệnh gọi kho từ tác vụ nền, để một bước chậm không bao giờ gây timeout.
Kiểm thử bằng hóa đơn demo
Tạo hóa đơn demo, thanh toán trên trang hosted và theo dõi endpoint của bạn nhận webhook trước khi đưa vào sản xuất.
FAQ
Phản hồi của API khác webhook thế nào?
Phản hồi API xác nhận thanh toán đã được tạo và trả về redirectUrl. Chỉ webhook báo trạng thái cuối của thanh toán.
Nếu endpoint của tôi ngừng hoạt động thì sao?
Việc gửi sẽ được thử lại, vì vậy bộ xử lý của bạn phải an toàn khi lặp lại. Hãy kiểm tra nhật ký thường xuyên và đối soát các đơn hàng còn chờ.
Tôi có thể tin webhook mà không có x-api-key không?
Không. Luôn kiểm tra header x-api-key trước khi thay đổi đơn hàng.
Tôi nên xử lý những trạng thái nào?
Xử lý paid cho thanh toán thành công và coi các trạng thái khác là thông tin. Tài liệu API liệt kê đầy đủ các giá trị.
