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

Step 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.

---

Step 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

---

Step 3: Download provider files (if 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 consumer-submitted evidence before preparing response

❗

Important: Not all disputes include provider-submitted files.

---

Step 4: Upload your 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
• Files must be readable and directly relevant to the dispute

When to use:

• When you decide to CHALLENGE a dispute

---

Step 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 resolution before formal challenge/acceptance
• Communicating with the provider about dispute specifics

❗️

Important: This endpoint is available only when the payment provider supports direct communication between merchants and consumers/providers.

---

Step 6: Accept or Challenge the dispute

Submit your final decision on how to handle the dispute.

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

Two actions available:

ACCEPTED

• You agree 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 WIN (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

Action cannot be reversed once submitted

---

Step 7: Track dispute resolution

Webhook Events involved:

• DISPUTE_CHALLENGE_PROCESSING
• DISPUTE_UNDER_REVIEW
• DISPUTE_ACCEPT_PROCESSING
• DISPUTE_WON
• DISPUTE_LOST

Possible final outcomes: