Dispute
The payload sent to your webhook endpoint when a dispute is created or updated, and how to handle each dispute lifecycle event.
Dispute Webhook Events
A dispute emits an event at each stage of its lifecycle:| Event | Fires when | What it usually means |
|---|---|---|
dispute.opened | A cardholder opens a dispute on a payment | Funds are held; prepare to respond |
dispute.challenged | Evidence has been submitted to contest the dispute | The dispute is being reviewed by the network |
dispute.accepted | The dispute was accepted (not contested) | The funds are returned to the cardholder |
dispute.cancelled | The dispute was withdrawn or cancelled | No further action needed |
dispute.expired | The response window passed without resolution | Typically resolves against you |
dispute.won | The dispute was resolved in your favor | Funds are retained |
dispute.lost | The dispute was resolved in the cardholder’s favor | Funds are returned to the cardholder |
dispute.lost with is_resolved_by_rdr: true. This is expected — the refund was issued automatically to prevent a formal chargeback.Handling Dispute Events
Whendispute.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.
Dispute Status and Stage
The dispute object reports its progress through two fields:| Field | Values |
|---|---|
dispute_status | dispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost |
dispute_stage | pre_dispute, dispute, pre_arbitration |
Related
Managing Disputes
Handle Payment Failures
Webhook Payload Schema
The amount involved in the dispute, represented as a string to accommodate precision.
The unique identifier of the business involved in the dispute.
The timestamp of when the dispute was created, in UTC.
The currency of the disputed amount, represented as an ISO 4217 currency code.
The unique identifier of the dispute.
The current stage of the dispute process.
pre_dispute, dispute, pre_arbitration The current status of the dispute.
dispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost The unique identifier of the payment associated with the dispute.
Whether the dispute was resolved by Rapid Dispute Resolution
Remarks