This guide walks you through the pre-arbitration lifecycle and resolution flow.

Pre-arbitration is a secondary challenge phase occurring when a merchant has successfully challenged a dispute, but the consumer’s financial institution continues the contest by rejecting the merchant's evidence or providing new information. It acts as a final checkpoint for both parties to settle the matter before escalating to a formal, costly judgment by the payment provider in the arbitration phase.

Pre-arbitration is part of the extended dispute lifecycle, defined here.

Pre-Arbitration Lifecycle

Status Definitions

Understanding pre-arbitration states helps you track progress and know what actions are available:

Pre-Arbitration Resolution Flow

1. Receive pre-arbitration notification

When a dispute is escalated to pre-arbitration against a merchant account, a PRE_ARBITRATION_ACTION_REQUIRED webhook notification is sent to the registered endpoint.

---

2. Retrieve pre-arbitration details

Retrieve detailed information about the dispute, including the reason, status, and any new files. Full list of reason codes can be accessed here.

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

When to use:

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

---

3. Download consumer files (if available)

Download any documentation or evidence submitted by the consumer/ consumer bank.

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 pre-arbitration details (if files are attached)
• To review consumer/ consumer bank submitted evidence before preparing a response

---

4. Add messages (optional)

Communicate directly with the consumer bank during the pre-arbitration resolution process by posting messages.

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

When to use:

• Direct communication with the consumer bank to resolve disputes amicably
• Negotiating a resolution before challenging/ accepting

❗️

Important: This endpoint is available only when the payment provider supports direct communication between merchants and consumers/ consumer banks. You will receive a webhook notification every time a new message is posted.

---

5. Upload supporting files

During communication with the consumer bank, upload documentation to support a case or to answer questions. 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:

• During communication with the consumer bank

❗️

Important: Files uploaded are immediately visible to consumers

---

6. Accept or challenge

Submit the final decision on how to handle the dispute.

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

ACCEPT

• Agreement with the consumer bank
• 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 the consumer bank
• Consumer bank reviews and reaches a decision
• May result in WON (merchant keeps funds) or LOST (funds returned to consumer)

❗️

Important:

Responses must be sent before the deadline (provided in the dispute details) otherwise the dispute is closed as status LOST

CHALLENGE may require evidence upload (Step 5) before submission

Actions cannot be reversed once submitted

Refunds are not automatically processed when accepting, they must be separately initiated

---

7. Track dispute resolution

Webhook events:

• PRE_ARBITRATION_ACCEPT_PROCESSING
• PRE_ARBITRATION_CHALLENGE_PROCESSING
• PRE_ARBITRATION_UNDER_REVIEW
• PRE_ARBITRATION_WON
• PRE_ARBITRATION_LOST

Possible final outcomes: