This guide walks you through the dispute resolution lifecycle, from receiving initial notifications to resolving disputes through acceptance or challenge.

Dispute Resolution Flow

Dispute Resolution Process

1. Receive dispute notification

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

---

2. Retrieve dispute details

Retrieve detailed information about a specific dispute, including the reason, status, consumer provided files and messages, as well as allowedActions and allowedCapabilities. A full list of reason codes can be accessed here.

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

When to use:

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

---

3. Download provider files (when available)

Download any documentation or evidence submitted by the payment provider or 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 dispute details (if files are attached)
• To review provider or consumer-submitted evidence before preparing a response

❗

Important: Not all disputes include provider or consumer-submitted files.

---

4. Upload supporting files (when allowed)

Upload supporting documentation to challenge the dispute and prove payment validity. 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:

• When the dispute will be challenged

---

5. Add messages (when allowed)

Communicate directly with the consumer or payment provider during the 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 a resolution before formal challenge/acceptance
• Communicating with the provider about dispute specifics

❗️

Important: Endpoint is only available when the payment provider supports direct communication between merchants and consumers/providers. You receive a webhook notification every time a new message is added.

---

6. Accept or challenge the dispute

Submit a final decision on how to handle the dispute. To check which actions are available, see allowedActions.

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

Two actions are possible:

ACCEPT

• Agreement with the dispute
• The disputed amount is returned to the consumer
• Dispute is closed (status: LOST)
• No evidence submission required

CHALLENGE

• The dispute is contested with evidence
• Previously uploaded evidence is submitted to provider
• Provider reviews and reaches a decision
• May result in WON (merchant keeps funds) or LOST (funds returned to consumer)

❗

Important:

A response is required before the deadline (see the action's dueBy date) otherwise the dispute will be closed by the provider with status: LOST

CHALLENGE requires evidence upload (Step 4) before submission

Actions cannot be reversed once submitted

7. Track dispute resolution

Webhook events:

• DISPUTE_CHALLENGE_PROCESSING
• DISPUTE_UNDER_REVIEW
• DISPUTE_ACCEPT_PROCESSING
• DISPUTE_WON
• DISPUTE_LOST

Possible final outcomes: