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:

Supported Payment Methods

The following payment methods utilize pre-disputes:

• Wero

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_OPEN 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, any consumer provided files and messages, as well as allowedActions and allowedCapabilitiess. Full list of reason codes can be accessed here.

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

When to use:

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

---

3. Download consumer files (when 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 (when files are attached)
• To review consumer-submitted evidence before preparing response

---

4. Add messages (when allowed)

Communicate directly with the consumer during the pre-dispute resolution process by posting messages. To check if messages can be added as well as the maximum characters allowed, see allowedCapabilities.

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 (when allowed)

During communication with the consumer, upload documentation to support a case or to answer questions from the consumer. Multiple files can be uploaded. To check if files can be uploaded as well as the accepted formats and file size limitations, see allowedCapabilities.

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

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. To check which actions are available, see allowedActions.

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 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:

A response is required before the deadline (see the action's dueBy date) otherwise the pre-dispute will likely be escalated by the consumer to a formal dispute

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 allowedActions for the pre-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: