Dispute Reporting & Responses

The Disputes API suite enables merchants to manage dispute cases programmatically. It provides two key capabilities:

• Disputes Reporting: Retrieve dispute case details, status history, and merchant responses.

• Dispute Response: Submit responses to eligible dispute cases, including supporting evidence and commentary.

Use these APIs to streamline dispute management for your merchant accounts.

Available APIs and Endpoints

1. Disputes Reporting API

Retrieve dispute case information and submitted responses.

• Get Dispute Cases: GET /api/disputes/v2.0/merchantdisputes

• Get Dispute Case History: GET /api/disputes/v2.0/merchantdisputes/{caseNumber}

• Get Submitted Merchant Dispute Response: GET /api/disputes/v2.0/merchantdisputes/{caseNumber}/responses

2. Dispute Response API

Submit a response for a specific dispute case.

• Submit Dispute Case Response: POST /api/disputes/v2.0/responses

Usage Information

To submit a response, ensure the following conditions are met:

Dispute Response Conditions

• Eligible Case Types: Chargebacks and Retrievals only.

• Status Requirements: Case must be in Awaiting Response or New Activity.

When Cases Aren’t Eligible

• Status is UnderReview or Completed → Returns 406 Not Acceptable.

• Case type is not Chargeback or Retrieval → Returns 406 Not Acceptable.

• Pre-Arb or Arb cases → Returns 406 Not Acceptable with message: You cannot respond to this case type using Xplor’s dispute management tool. The merchant will receive a letter with instructions. For more information, call +1.844.663.8797 with the case number ready. Pursuing this type of case can incur significant fees for the losing party.

Evidence Submission

Allowed for Retrievals and Chargebacks.

Field	Limit
caseNumber	Required
responseMessage	Max 500 characters
evidences	Only .tiff, .tif, .pdf, .jpg, .jpeg allowed
File Size	Max 10 MB per file (configurable)
File Name	Max 50 characters (configurable)

Request Example

Submit a response using the POST endpoint:

curl -H "Content-Type: application/json" -X POST "https://horizon-service.clearent.net/api/disputes/v2.0/responses" -d '{
    "caseNumber": "CHB123456789",
    "response": "Response message",
    "responseType": 1 (can be only 1 or 2)
}'

Request Schema

{
  "caseNumber": "ABC123456789",
  "response": "My response message",
  "responseType": number (can be only 1 or 2)
}

Note: Providing only response text without attachments may return an error for certain dispute case types.

Response Schema Properties

Element or Property	Data Type	Description
CaseNumber	String	The unique number assigned to a dispute case.
Response	String	The message provided by the merchant as a response.
responseType	Number	Indicates the type of response: 1 = Accept? Adds “I Accept” to response. 2 = Reject? Adds “I Reject” to response.