Webhook 事件指南

Dodo Payments 会在支付、订阅、争议、打款、额度或许可证密钥生命周期的每个阶段发出 webhook 事件。本页面按资源列出所有事件。有关详细的 payload schema 和处理程序示例，请参阅下方链接的资源专属页面。

支付事件

事件	触发时机
`payment.succeeded`	支付成功处理完成时。
`payment.failed`	支付尝试因卡片被拒、余额不足或其他错误而失败时。
`payment.processing`	支付正在处理时。
`payment.cancelled`	支付在完成前被取消时。

有关完整的 payload schema，请参阅 Payment Webhooks。

退款事件

事件	触发时机
`refund.succeeded`	退款成功处理完成时。
`refund.failed`	退款尝试因处理错误或其他问题而失败时。

有关完整的 payload schema，请参阅 Refund Webhooks。

争议事件

事件	触发时机
`dispute.opened`	持卡人对某笔支付发起争议时。
`dispute.challenged`	已提交证据以对争议提出异议时。
`dispute.accepted`	争议在未提出异议的情况下被接受时。
`dispute.cancelled`	争议被撤回或取消时。
`dispute.expired`	回复期限已过但争议仍未解决时。
`dispute.won`	争议裁定对您有利时。
`dispute.lost`	争议裁定对持卡人有利时。

有关详细的 payload schema 和处理程序示例，请参阅 Dispute Webhooks。

订阅事件

事件	触发时机
`subscription.active`	订阅成功激活并安排定期扣款时。
`subscription.updated`	任意订阅字段发生变化时（实时同步，无需轮询）。
`subscription.past_due`	续订失败并进入宽限期时；客户在截止时间前仍可继续访问。
`subscription.on_hold`	订阅因续订失败而被暂时搁置时。
`subscription.paused`	订阅被暂停时。
`subscription.unpaused`	已暂停的订阅恢复时。
`subscription.renewed`	订阅成功续订至下一个计费周期时。
`subscription.plan_changed`	订阅升级、降级或修改为不同的附加项时。
`subscription.update_payment_method`	订阅的支付方式更新时。
`subscription.cancelled`	订阅被商户或客户取消时。
`subscription.failed`	创建 mandate 期间订阅创建失败时。
`subscription.expired`	订阅达到期限末尾并过期时。

有关详细的 payload schema 和处理程序示例，请参阅 Subscription Webhooks。

许可证密钥事件

事件	触发时机
`license_key.created`	为产品创建新的许可证密钥时。

有关完整的 payload schema，请参阅 License Key Webhooks。

权益授予事件

事件	触发时机
`entitlement_grant.created`	为客户创建新的权益授予时。自动履行的许可证密钥授予和功能标志授予会随 `status: "Delivered"` 一起到达，不会单独触发 `delivered` 事件。其他授予（包括手动履行的许可证密钥）会随 `Pending` 到达。请参阅 Entitlement Grant。
`entitlement_grant.delivered`	权益授予履行完成——许可证密钥已签发、文件链接已解析或平台访问权限已授予时。
`entitlement_grant.failed`	权益授予履行失败时。请检查 payload 中的 `error_code` 和 `error_message`。
`entitlement_grant.revoked`	访问权限被撤回时。请检查 payload 中的 `revocation_reason`。

有关详细的 payload schema、示例事件以及完整的 revocation_reason 参考，请参阅 Entitlement Grant Webhooks。

额度事件

事件	触发时机
`credit.added`	向客户授予额度时（通过订阅、一次性购买、附加项或 API）。
`credit.deducted`	额度通过使用或手动扣减被消耗时。
`credit.expired`	未使用的额度在配置的过期时间后过期时。
`credit.rolled_over`	未使用的额度在周期结束时结转至新的授予时。
`credit.rollover_forfeited`	因达到最大结转次数，额度被没收时。
`credit.overage_charged`	对超过零余额的使用量收取超额费用时。
`credit.overage_reset`	累积的超额费用被重置时（例如，在新的计费周期开始时）。
`credit.manual_adjustment`	进行手动额度或扣减调整时。
`credit.balance_low`	额度余额低于配置的阈值时。

有关详细的 payload schema 和处理程序示例，请参阅 Credit-Based Billing Webhooks。

恢复事件

事件	触发时机
`abandoned_checkout.detected`	在 60 分钟后检测到未完成或失败的结账时。
`abandoned_checkout.recovered`	客户通过恢复链接完成支付时。

有关详细的 payload schema、字段说明和处理程序示例，请参阅 Recovery Webhooks。

催收事件

事件	触发时机
`dunning.started`	对已逾期、搁置或已取消的订阅开始催收尝试时。
`dunning.recovered`	客户更新支付方式且由此产生的扣款成功时。

有关详细的 payload schema、字段说明和处理程序示例，请参阅 Recovery Webhooks。

打款事件

打款事件用于跟踪您的资金从 Dodo Payments 转入银行账户的过程。它们与控制面板中显示的打款状态相对应。payload 是一个打款对象，其结构与 GET /payouts 中的条目相同。

事件	触发时机
`payout.created`	通过自动打款周期或周期外流程创建打款时。
`payout.in_progress`	打款到期日到达并开始处理时。
`payout.on_hold`	打款被暂停或进入审核时。
`payout.success`	向银行账户的打款结算时。
`payout.failed`	打款失败时。资金和费用会退回至您的钱包。

打款事件既不是终止性的，也不一定严格按顺序到达。当银行退回转账时，payout.failed 可能会在 payout.success 之后到达；当失败的打款随后恢复时，payout.success 也可能会在 payout.failed 之后到达。payload 中的 status 始终与事件类型一致，因此请使用每个事件顶层的 timestamp 来查找最新状态。

payout.created 之前曾以 payout.not_initiated 的形式发出。如果现有 endpoint 根据 payout.not_initiated 进行筛选，请将筛选条件更新为 payout.created，以便继续匹配。

有关详细的 payload schema、字段说明和处理程序示例，请参阅 Payout Webhooks。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

支付事件

退款事件

争议事件

订阅事件

许可证密钥事件

权益授予事件

额度事件

恢复事件

催收事件

打款事件

​支付事件

​退款事件

​争议事件

​订阅事件

​许可证密钥事件

​权益授予事件

​额度事件

​恢复事件

​催收事件

​打款事件

支付事件

退款事件

争议事件

订阅事件

许可证密钥事件

权益授予事件

额度事件

恢复事件

催收事件

打款事件