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_OPEN 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_OPEN webhook
• To check current status of in-progress disputes

---

3. Download 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. 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 allowedCapabilitiesin the dispute details API response body.

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: This endpoint is available only when the payment provider supports direct messaging and it is supported in the respective phase. See each supported payment provider's page for the exact settings, such as whether messaging is supported. You will receive a webhook notification every time a new message is posted.

---

5. 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 allowedCapabilitiesin the dispute details API response body.

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

When to use:

• When the dispute will be challenged

📘

Important: The file upload endpoint is used for sending files as part of the messaging feature and when challenging a dispute. If, for example, messaging is supported by the provider, you use the file upload endpoint to attach files to your messages. If messaging is not supported, you use the file upload endpoint to upload your evidence before you challenge.

⚠️

Important: Files uploaded may be immediately visible to the provider or consumer. See each supported payment provider's page for more information.

---

6. Accept or challenge

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 may require evidence upload (Step 5) before submission

Actions cannot be reversed once submitted

7. Track dispute resolution

Webhook events:

• DISPUTE_CHALLENGE_PROCESSING
• DISPUTE_UNDER_REVIEW
• DISPUTE_UPDATED
• DISPUTE_ACCEPT_PROCESSING
• DISPUTE_WON
• DISPUTE_LOST

Possible final outcomes: