Chuyển đến nội dung chính
Merchant of Record của bạn, Dodo Payments quản lý quy trình tranh chấp và hoàn tiền với mạng lưới thẻ thay mặt cho bạn. Những webhook này giữ cho hệ thống của bạn đồng bộ khi một tranh chấp di chuyển qua vòng đời của nó để bạn có thể thu hồi quyền truy cập, thu thập bằng chứng và đối chiếu hồ sơ của mình.

Các Sự Kiện Webhook Tranh Chấp

Một tranh chấp phát đi một sự kiện ở mỗi giai đoạn của vòng đời của nó:
Sự kiệnKích hoạt khi nàoĐiều này thường có nghĩa là gì
dispute.openedChủ thẻ mở một tranh chấp về một khoản thanh toánTiền bị giữ lại; chuẩn bị để đáp ứng
dispute.challengedBằng chứng đã được nộp để tranh luận tranh chấpTranh chấp đang được mạng lưới xem xét
dispute.acceptedTranh chấp đã được chấp nhận (không tranh cãi)Tiền được hoàn lại cho chủ thẻ
dispute.cancelledTranh chấp đã được rút lại hoặc hủy bỏKhông cần hành động nào thêm
dispute.expiredCửa sổ phản hồi đã qua mà không có kết quả giải quyếtThường thì quyết định không có lợi cho bạn
dispute.wonTranh chấp được giải quyết có lợi cho bạnTiền được giữ lại
dispute.lostTranh chấp được giải quyết có lợi cho chủ thẻTiền được hoàn lại cho chủ thẻ
Các tranh chấp tự động giải quyết thông qua Visa Rapid Dispute Resolution (RDR) xuất hiện dưới dạng dispute.lost với is_resolved_by_rdr: true. Điều này được mong đợi — việc hoàn tiền được thực hiện tự động để ngăn chặn một hoàn tiền chính thức.

Xử Lý Các Sự Kiện Tranh Chấp

Khi dispute.opened kích hoạt, số tiền bị tranh chấp được giữ lại ngay lập tức. Sử dụng sự kiện để cập nhật hồ sơ của bạn và, nếu bạn định tranh cãi, thu thập bằng chứng trong bảng điều khiển.
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 });
});
Luôn xác minh chữ ký webhook trước khi xử lý — xem hướng dẫn Webhooks để thiết lập. Trình xử lý trên bỏ qua xác minh để ngắn gọn.
Bạn có 4 ngày để phản hồi một tranh chấp sau khi nó được tạo. Xem Các Thực Hành Tốt Nhất Phản Hồi Tranh Chấp để biết các bằng chứng cần thu thập và cách định dạng.

Trạng Thái và Giai Đoạn Tranh Chấp

Đối tượng tranh chấp báo cáo tiến trình của nó thông qua hai trường:
TrườngGiá trị
dispute_statusdispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost
dispute_stagepre_dispute, dispute, pre_arbitration

Liên Quan

Managing Disputes

Cách phản hồi tranh chấp, nộp bằng chứng và cách RDR bảo vệ tỷ lệ tranh chấp của bạn.

Handle Payment Failures

Phát hiện và phục hồi các thanh toán thất bại trước khi chúng trở thành tranh chấp.

Sơ Đồ Payload Webhook

amount
string
bắt buộc

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

business_id
string
bắt buộc

The unique identifier of the business involved in the dispute.

created_at
string<date-time>
bắt buộc

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

currency
string
bắt buộc

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

dispute_id
string
bắt buộc

The unique identifier of the dispute.

dispute_stage
enum<string>
bắt buộc

The current stage of the dispute process.

Tùy chọn có sẵn:
pre_dispute,
dispute,
pre_arbitration
dispute_status
enum<string>
bắt buộc

The current status of the dispute.

Tùy chọn có sẵn:
dispute_opened,
dispute_expired,
dispute_accepted,
dispute_cancelled,
dispute_challenged,
dispute_won,
dispute_lost
payment_id
string
bắt buộc

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

Lần sửa đổi cuối 18 tháng 6, 2026