Skip to main content
As your Merchant of Record, Dodo Payments manages the dispute and chargeback process with the card networks on your behalf. These webhooks keep your systems in sync as a dispute moves through its lifecycle so you can revoke access, gather evidence, and reconcile your records.

Dispute Webhook Events

A dispute emits an event at each stage of its lifecycle:
Disputes auto-resolved through Visa Rapid Dispute Resolution (RDR) appear as dispute.lost with is_resolved_by_rdr: true. This is expected — the refund was issued automatically to prevent a formal chargeback.
Ethoca alerts and deflections never create a dispute, so they emit no dispute.* events. An Ethoca alert refund fires the standard refund.succeeded event, and any linked subscription cancellation fires the usual subscription event. A deflection fires no event.

Handling Dispute Events

When dispute.opened fires, the disputed amount is held immediately. Use the event to update your records and, if you intend to contest it, gather evidence in the dashboard.
Handling dispute events
Always verify the webhook signature before processing — see the Webhooks guide for setup. The handler above omits verification for brevity.
You have 10 days to respond to a dispute after it is created. See Dispute Response Best Practices for the evidence to gather and how to format it.

Dispute Status and Stage

The dispute object reports its progress through two fields:

Managing Disputes

How to respond to disputes, submit evidence, and how RDR protects your dispute rate.

Handle Payment Failures

Detect and recover failed payments before they become disputes.

Webhook Payload Schema

amount
string
required

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

brand_id
string
required

Brand id this dispute belongs to

business_id
string
required

The unique identifier of the business involved in the dispute.

created_at
string<date-time>
required

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

currency
string
required

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

customer
object
required

The customer who filed the dispute

dispute_id
string
required

The unique identifier of the dispute.

dispute_stage
enum<string>
required

The current stage of the dispute process.

Available options:
pre_dispute,
dispute,
pre_arbitration
dispute_status
enum<string>
required

The current status of the dispute.

Available options:
dispute_opened,
dispute_expired,
dispute_accepted,
dispute_cancelled,
dispute_challenged,
dispute_won,
dispute_lost
payment_id
string
required

The unique identifier of the payment associated with the dispute.

payment_provider
enum<string>
required

Which processor handled the underlying payment. stripe / adyen for BYOP routes (the merchant's own payment connector); dodo for everything Dodo processed itself.

Available options:
stripe,
adyen,
dodo
is_resolved_by_rdr
boolean | null

Whether the dispute was resolved by Rapid Dispute Resolution

reason
string | null

Reason for the dispute

remarks
string | null

Remarks

Last modified on September 25, 2026