跳转到主要内容
作为您的商户记录,Dodo Payments 代表您管理与银行卡网络的争议和拒付流程。这些 webhook 在争议的生命周期中保持您的系统同步,以便您可以撤销访问权、收集证据并对记录进行核对。

争议 Webhook 事件

争议在其生命周期的每个阶段会触发一个事件:
事件触发时间通常意味着
dispute.opened持卡人在付款上提出争议资金被冻结;准备应对
dispute.challenged已提交证据以对争议进行抗辩争议由网络审查中
dispute.accepted争议被接受(未抗辩)资金退还给持卡人
dispute.cancelled争议已撤回或取消无需进一步行动
dispute.expired响应窗口过期未解决通常对您不利解决
dispute.won争议以您的有利方式解决资金保留
dispute.lost争议以持卡人有利解决资金退还给持卡人
通过Visa 快速争议解决 (RDR)自动解决的争议显示为 dispute.lostis_resolved_by_rdr: true。这是预期的——退款是自动发出的,以防止正式拒付。

处理争议事件

dispute.opened 触发时,争议金额会立即被冻结。使用该事件更新您的记录,并且如果您打算抗辩,请在仪表盘中收集证据。
Handling dispute events
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'dispute.opened': {
      const dispute = event.data;
      // Record the dispute and consider revoking access while it is open
      await recordDispute(dispute.dispute_id, dispute.payment_id, dispute.amount);
      // Gather and submit evidence from the Dodo Payments dashboard (within 4 days)
      break;
    }
    case 'dispute.won': {
      // Funds retained — restore normal state in your records
      await markDisputeResolved(event.data.dispute_id, 'won');
      break;
    }
    case 'dispute.lost': {
      // Funds returned to the cardholder — reconcile and keep access revoked
      await markDisputeResolved(event.data.dispute_id, 'lost');
      break;
    }
  }

  res.json({ received: true });
});
在处理前始终验证 webhook 签名——请参阅 Webhook 指南 进行设置。上面的处理程序为了简洁省略了验证。
您有 4 天的时间来响应争议。请参阅争议响应最佳实践以了解收集的证据及其格式要求。

争议状态和阶段

争议对象通过两个字段报告其进度:
字段
dispute_statusdispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost
dispute_stagepre_dispute, dispute, pre_arbitration

相关

Managing Disputes

如何响应争议、提交证据以及 RDR 如何保护您的争议率。

Handle Payment Failures

在付款失败成为争议之前检测并恢复它们。

Webhook 有效负载架构

amount
string
必填

The amount involved in the dispute, represented as a string to accommodate precision.

business_id
string
必填

The unique identifier of the business involved in the dispute.

created_at
string<date-time>
必填

The timestamp of when the dispute was created, in UTC.

currency
string
必填

The currency of the disputed amount, represented as an ISO 4217 currency code.

dispute_id
string
必填

The unique identifier of the dispute.

dispute_stage
enum<string>
必填

The current stage of the dispute process.

可用选项:
pre_dispute,
dispute,
pre_arbitration
dispute_status
enum<string>
必填

The current status of the dispute.

可用选项:
dispute_opened,
dispute_expired,
dispute_accepted,
dispute_cancelled,
dispute_challenged,
dispute_won,
dispute_lost
payment_id
string
必填

The unique identifier of the payment associated with the dispute.

is_resolved_by_rdr
boolean | null

Whether the dispute was resolved by Rapid Dispute Resolution

remarks
string | null

Remarks

最后修改于 2026年6月18日