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

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

• When the dispute will be challenged

---

5. Add messages (optional)

Communicate directly with the consumer or payment provider during the 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 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.

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

Two actions available:

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:

Must respond before deadline (provided in dispute details) otherwise dispute is closed (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: