Disputes
A dispute (also known as a chargeback) occurs when a cardholder or bank account holder questions a transaction with their card issuer or bank. When a dispute is filed, the card network immediately reverses the payment — the disputed funds are withdrawn from the merchant's account and held until the dispute is resolved.
Get Started
To integrate Disputes, follow the Integration Guide for webhook event details, payload schemas, and evidence submission guidance.
Key Benefits
- Protects merchants from fraudulent or erroneous chargebacks
- Provides real-time visibility into dispute status and outcomes
- Enables proactive evidence submission to maximize win rates
- Reduces financial risk by clarifying dispute flows and deadlines
How It Works
Disputes progress through a series of events from initiation to resolution. The typical flow is:
Dispute Lifecycle Events:
- Dispute Initiated — The dispute is filed. Funds are at risk. Status:
NEEDS_RESPONSEorWARNING_NEEDS_RESPONSE. - Funds Withdrawn — Disputed amount debited from merchant. Status:
NEEDS_RESPONSE. - Won — Funds reinstated to merchant. Not terminal; a Closed event follows. Status:
WON. - Closed — Terminal event. Status:
WONorLOST.
Not every dispute follows every step — some may resolve directly after initiation.
Responding to Disputes:
- Receive notification of dispute initiation.
- Gather and submit evidence before the deadline (typically 7–21 days).
- Monitor outcome via dispute closed event.
Dispute Statuses:
| Status | Description |
|---|---|
NEEDS_RESPONSE | Dispute filed. Evidence required. |
UNDER_REVIEW | Evidence submitted, under review. |
WON | Dispute resolved in merchant's favor. |
LOST | Dispute resolved in cardholder's favor. |
WARNING_NEEDS_RESPONSE | Early fraud warning, response required. |
WARNING_UNDER_REVIEW | Early fraud warning under review. |
WARNING_CLOSED | Early fraud warning closed. |
Business Rules
Pre-Conditions
- Transaction must be completed and settled.
- Dispute must be filed by cardholder or issuing bank.
Post-Conditions
- Funds may be withdrawn from merchant account during dispute.
- Final outcome (won/lost) is communicated via closed event.
Constraints
- Evidence must be submitted before the processor's deadline.
- Dispute fees are non-refundable, regardless of outcome.
- Dispute reason codes and deadlines are set by the payment processor.
Scenarios
Standard Scenarios
| Scenario | Description |
|---|---|
| Dispute Initiated | Cardholder files a dispute; merchant notified. |
| Funds Withdrawn | Disputed funds debited from merchant. |
| Merchant Wins | Merchant submits evidence and wins; funds reinstated. |
| Merchant Loses | Merchant does not respond or loses; funds permanently deducted. |