Hướng Dẫn Sự Kiện Webhook - Dodo Payments Documentation

Dodo Payments cung cấp thông báo webhook theo thời gian thực để giữ cho bạn được thông báo về các sự kiện quan trọng liên quan đến giao dịch, đăng ký, hoàn tiền, tranh chấp và quản lý khóa bản quyền. Dưới đây là hướng dẫn chi tiết về các sự kiện này, được phân loại để dễ hiểu, cùng với các mẹo và cân nhắc khi triển khai.

Sự Kiện Thanh Toán

Event Name	Event Type	Description
Payment Succeeded	`payment.succeeded`	Được kích hoạt khi một khoản thanh toán được xử lý thành công.
Payment Failed	`payment.failed`	Xảy ra khi một lần thử thanh toán thất bại do lỗi, thẻ bị từ chối hoặc các vấn đề khác.
Payment Processing	`payment.processing`	Cho biết một khoản thanh toán đang được xử lý.
Payment Cancelled	`payment.cancelled`	Được kích hoạt khi một khoản thanh toán bị hủy trước khi hoàn tất.

Sự Kiện Hoàn Tiền

Event Name	Event Type	Description
Refund Succeeded	`refund.succeeded`	Được kích hoạt khi hoàn tiền được xử lý thành công.
Refund Failed	`refund.failed`	Xảy ra khi một lần thử hoàn tiền thất bại do lỗi xử lý hoặc các vấn đề khác.

Sự Kiện Tranh Chấp

Event Name	Event Type	Description
Dispute Opened	`dispute.opened`	Được kích hoạt khi khách hàng khởi xướng tranh chấp.
Dispute Expired	`dispute.expired`	Cho biết tranh chấp đã hết hạn mà không được giải quyết.
Dispute Accepted	`dispute.accepted`	Được kích hoạt khi thương nhân chấp nhận tranh chấp.
Dispute Cancelled	`dispute.cancelled`	Xảy ra khi tranh chấp bị khách hàng hoặc hệ thống hủy bỏ.
Dispute Challenged	`dispute.challenged`	Được kích hoạt khi thương nhân phản bác tranh chấp.
Dispute Won	`dispute.won`	Cho biết thương nhân đã thắng tranh chấp.
Dispute Lost	`dispute.lost`	Xảy ra khi thương nhân thua một tranh chấp.

Sự Kiện Đăng Ký

Event Name	Event Type	Description
Subscription Active	`subscription.active`	Cho biết một đăng ký hiện đang hoạt động và các khoản phí định kỳ đã được lên lịch.
Subscription Updated	`subscription.updated`	Được kích hoạt khi bất kỳ trường đăng ký nào được cập nhật (đồng bộ thời gian thực mà không cần kiểm tra).
Subscription On Hold	`subscription.on_hold`	Được kích hoạt khi một đăng ký tạm thời bị tạm dừng do việc gia hạn thất bại.
Subscription Renewed	`subscription.renewed`	Xảy ra khi một đăng ký được gia hạn thành công.
Subscription Plan Changed	`subscription.plan_changed`	Được kích hoạt khi một đăng ký được nâng cấp, hạ cấp hoặc chỉnh sửa với các phần bổ trợ khác nhau.
Subscription Cancelled	`subscription.cancelled`	Được kích hoạt khi một đăng ký bị hủy bởi thương nhân hoặc khách hàng.
Subscription Failed	`subscription.failed`	Cho biết đăng ký thất bại. Điều này có nghĩa là chúng tôi không thể tạo một ủy quyền.
Subscription Expired	`subscription.expired`	Được kích hoạt khi một đăng ký đạt đến cuối hạn và hết hạn.

Sự Kiện Khóa Bản Quyền

Event Name	Event Type	Description
License Key Created	`license_key.created`	Được kích hoạt khi một khóa cấp phép mới được tạo cho sản phẩm.

Các Sự Kiện Cấp Quyền

Tên Sự Kiện	Loại Sự Kiện	Mô Tả
Cấp Quyền Đã Tạo	`entitlement_grant.created`	Một cấp quyền mới được tạo cho một khách hàng. Các cấp quyền khóa giấy phép đến `delivered`; các cấp quyền dựa trên OAuth (Discord, GitHub, Notion) đến `pending`.
Cấp Quyền Đã Giao	`entitlement_grant.delivered`	Hoàn tất việc cấp quyền — khóa giấy phép đã cấp, liên kết tệp đã giải quyết, hoặc quyền truy cập vào nền tảng đã được cấp.
Cấp Quyền Thất Bại	`entitlement_grant.failed`	Việc giao cấp quyền thất bại; kiểm tra `error_code` và `error_message`.
Cấp Quyền Bị Thu Hồi	`entitlement_grant.revoked`	Quyền truy cập bị rút lại; kiểm tra `revocation_reason` (trạng thái đăng ký, hoàn tiền, thay đổi gói, hoặc thủ công).

Để biết chi tiết về các lược đồ tải trọng, sự kiện mẫu và tham chiếu đầy đủ revocation_reason, xem Webhook Cấp Quyền.

Các Sự Kiện Tín Dụng

Tên Sự Kiện	Loại Sự Kiện	Mô Tả
Tín Dụng Đã Thêm	`credit.added`	Được kích hoạt khi tín dụng được cấp cho một khách hàng (đăng ký, một lần, bổ sung hoặc API).
Tín Dụng Đã Khấu Trừ	`credit.deducted`	Xảy ra khi tín dụng được tiêu thụ thông qua sử dụng hoặc ghi nợ thủ công.
Tín Dụng Đã Hết Hạn	`credit.expired`	Được kích hoạt khi tín dụng không sử dụng hết hạn sau thời gian hết hạn được cấu hình.
Tín Dụng Được Cộng Dồn	`credit.rolled_over`	Xảy ra khi tín dụng không sử dụng được cộng dồn sang lần cấp mới khi kết thúc chu kỳ.
Cộng Dồn Bị Tước Quyền	`credit.rollover_forfeited`	Được kích hoạt khi tín dụng bị tước quyền vì giới hạn cộng dồn tối đa đã đạt đến.
Quá Mức Bị Tính Phí	`credit.overage_charged`	Xảy ra khi các khoản phí quá mức được áp dụng cho việc sử dụng vượt quá số dư bằng không.
Điều Chỉnh Thủ Công	`credit.manual_adjustment`	Được kích hoạt khi có điều chỉnh tín dụng hoặc ghi nợ thủ công.
Số Dư Thấp	`credit.balance_low`	Được kích hoạt khi số dư tín dụng giảm dưới ngưỡng đã cấu hình.

Các Sự Kiện Khôi Phục

Tên Sự Kiện	Loại Sự Kiện	Mô Tả
Phát Hiện Thanh Toán Bị Bỏ Rơi	`abandoned_checkout.detected`	Được kích hoạt khi phát hiện thanh toán không hoàn tất hoặc thất bại sau 60 phút.
Khôi Phục Thanh Toán Bị Bỏ Rơi	`abandoned_checkout.recovered`	Xảy ra khi một khách hàng hoàn tất thanh toán thông qua liên kết khôi phục.

Để biết chi tiết về lược đồ payload, mô tả trường, và ví dụ về xử lý, xem Recovery Webhooks.

Các Sự Kiện Dunning

Tên Sự Kiện	Loại Sự Kiện	Mô Tả
Dunning Bắt Đầu	`dunning.started`	Được kích hoạt khi một cố gắng dunning bắt đầu cho một đăng ký đã bị tạm dừng hoặc bị hủy.
Dunning Khôi Phục	`dunning.recovered`	Xảy ra khi một khách hàng cập nhật phương thức thanh toán và việc tính phí thành công.

Để biết chi tiết về các lược đồ tải trọng, mô tả trường và ví dụ về trình xử lý, xem Webhook Khôi Phục. Các sự kiện webhook này được thiết kế để cung cấp cho người bán các cập nhật quan trọng để quản lý hoạt động của họ một cách hiệu quả. Thực hiện các trình xử lý mạnh mẽ cho mỗi sự kiện liên quan trong tích hợp webhook của bạn để đảm bảo chức năng suôn sẻ và đáng tin cậy.

​Sự Kiện Thanh Toán

​Sự Kiện Hoàn Tiền

​Sự Kiện Tranh Chấp

​Sự Kiện Đăng Ký

​Sự Kiện Khóa Bản Quyền

​Các Sự Kiện Cấp Quyền

​Các Sự Kiện Tín Dụng

​Các Sự Kiện Khôi Phục

​Các Sự Kiện Dunning