This guide walks you through the pre-dispute lifecycle and resolution flow.

A pre-dispute is an early-warning stage where merchants resolve customer issues via a refund or explanation before it becomes a formal dispute.

Pre-disputes are part of the extended dispute lifecycle, defined here.

Why Pre-Disputes Occur

Pre-disputes arise from similar issues as formal disputes, but the consumer opts for direct engagement first:

Pre-Dispute Lifecycle

Status Definitions

Understanding pre-dispute states helps you track progress and know what actions are available:

Pre-Disputes Resolution Flow

Pre-Disputes Resolution Process

1. Receive pre-dispute notification

When a pre-dispute is created against a merchant account, a PRE_DISPUTE_ACTION_REQUIRED webhook notification is sent to the registered endpoint.

---

2. Retrieve pre-dispute details

Retrieve detailed information about a specific pre-dispute, including the reason, status, and any consumer provided files. Full list of reason codes can be accessed here.

API endpoint: GET /v1/disputes/{disputeId}

When to use:

• Immediately after receiving PRE_DISPUTE_ACTION_REQUIRED webhook
• To check current status of in-progress pre-disputes

---

3. Download consumer files (if available)

Download any documentation or evidence submitted by consumer.

API endpoint: GET /v1/disputes/{disputeId}/files/{fileId}

The response provides:

• A time-limited download URL for secure file access
• File metadata (name, type, size)

When to use:

• After retrieving pre-dispute details (if files are attached)
• To review consumer-submitted evidence before preparing response

---

4. Add messages (optional)

Communicate directly with the consumer during the pre-dispute resolution process by posting messages.

API endpoint: POST /v1/disputes/{disputeId}/messages

When to use:

• Direct communication with the consumer to resolve disputes amicably
• Negotiating resolution before challenging/accepting/offering

❗️

Important: This endpoint is available only when the payment provider supports direct communication between merchants and consumers. A webhook notification is posted every time a new message is received.

---

5. Upload supporting files

During communication with the consumer, upload documentation to support a case or to answer questions from the consumer. Multiple files can be uploaded.

API endpoint: POST /v1/disputes/{disputeId}/files

File Requirements:

• Accepted formats: PDF (other formats pending)
• Maximum file size: 10MB
• Maximum number of pages: 10
• Files must be readable and directly relevant to the dispute

When to use:

• During communication with the consumer

❗️

Important: Files uploaded are immediately visible to consumers

---

6. Accept, challenge or make an offer

Submit the final decision on how to handle the pre-dispute.

API endpoint: POST /v1/disputes/{disputeId}/actions

ACCEPT

• Agreement with the consumer
• Allows for a refund or replacement
• Will result in status LOST if the consumer takes no further action or if the consumer decides to escalate to a formal dispute (for example, if they do not receive their refund)

CHALLENGE

• The pre-dispute is contested with evidence
• The consumer may send more messages and files
• Will result in status WON if the consumer takes no further action or status LOST if the consumer decides to escalate to a formal dispute

OFFER

• An informal agreement with the consumer via made with a custom offer such as a gift card
• Will result in several statuses: status OFFER_ACCEPTED if the consumer accepts the offer or status OFFER_REJECTED if the consumer rejects the offer, finally status WON if the consumer takes no further action or status LOST if the consumer decides to escalate to a formal dispute

❗️

Important:

Responses must be sent before the deadline (provided in the pre-dispute details) otherwise the pre-dispute is closed as status LOST

CHALLENGE may require evidence upload (Step 5) before submission

Some providers require a resolution for ACCEPT, e.g. Full-refund, Partial-refund, Replacement, which is detailed in the allowed actions for the dispute

Actions cannot be reversed once submitted

Refunds are not automatically processed when accepting, they must be separately initiated

---

7. Track dispute resolution

Webhook events:

• PRE_DISPUTE_ACCEPT_PROCESSING
• PRE_DISPUTE_CHALLENGE_PROCESSING
• PRE_DISPUTE_OFFER_PROCESSING
• PRE_DISPUTE_UNDER_REVIEW
• PRE_DISPUTE_OFFER_ACCEPTED
• PRE_DISPUTE_OFFER_REJECTED
• PRE_DISPUTE_WON
• PRE_DISPUTE_LOST

Possible final outcomes: