Integration Flow

Dispute Management Flow

Detailed Integration Steps

Step 1: Receive Dispute Notifications

What happens: When a dispute is filed against your merchant account, our platform sends a webhook notification to your registered endpoint.

Webhook Event: DISPUTE_ACTION_REQUIRED

Next Steps:

• Store the dispute ID for future API calls
• Proceed to Step 2 to gather detailed information

ℹ️

Reference

See Webhooks API documentation for complete notification payload structure and event types.

---

Step 2: Retrieve Dispute Details

API Endpoint: GET /disputes/{disputeId}

Purpose: Fetch comprehensive information about a specific dispute to understand what's being contested and why.

When to use:

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

💡

Tip

Always check for existing disputes on a transaction to avoid responding multiple times to the same issue.

---

Step 3: Download Provider Evidence (if available)

API Endpoint: GET /disputes/{disputeId}/files/{fileId}

Purpose: Retrieve any supporting documentation or evidence submitted by the payment provider or consumer.

The download provides:

• 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
• To understand the basis of the dispute

❗

Important

Not all disputes include provider-submitted files

---

Step 4: Upload Your Evidence

API Endpoint: POST /disputes/{disputeId}/files

Purpose: Submit supporting documentation to challenge the dispute and prove transaction validity. Multiple files upload supported

Common Evidence Types by Reason Codes can be accessed here

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

Process:

• Initiate upload via API to receive secure URL
• Upload file to provided secure URL
• File is automatically associated with the dispute
• Repeat for additional evidence files

---

Step 5: Add Messages (Optional)

API Endpoint: POST /disputes/{disputeId}/messages

Purpose: Communicate directly with the consumer or payment provider during the dispute resolution process.

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

Use messaging for:

• Direct communication with the consumer to resolve disputes amicably
• Negotiating resolution before formal challenge/acceptance
• Communicating with the provider about dispute specifics

---

Step 6: Accept or Challenge the Dispute

API Endpoint: POST /disputes/{disputeId}/actions

Purpose: Submit your final decision on how to handle the dispute.

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 to a decision
• May result in WIN (merchant keeps funds) or LOST (consumer gets refund)

**Important Requirements:

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