Dispute Management
The Disputes API provides comprehensive tools to manage disputes related to transactions in your merchant account. Handle chargebacks, upload evidence, and monitor dispute resolutions programmatically to protect your business and maintain customer relationships.
Overview
What are disputes?
Disputes are typically initiated by customers through their issuing bank when they challenge a transaction. Common reasons include fraud, authorization issues, processing errors, or customer satisfaction concerns. The Disputes API allows you to programmatically handle these disputes, submit evidence, and track their resolution status.
Retrieve all disputes associated with your merchant account with advanced filtering and pagination.
Submit supporting evidence files to strengthen your dispute case and improve resolution outcomes.
Get real-time notifications when new disputes are created or status changes occur.
Key Features
Dispute Retrieval
- Paginated dispute listings (10 results per page)
- Filter by status, reason, date range, or transaction ID
- Sort by response deadline, creation date, or status
- Track dispute lifecycle and resolution progress
Evidence Management
- Upload multiple file types (.jpeg, .pdf, .png, .tiff)
- Maximum file size: 10MB per document
- Organize evidence with custom names and descriptions
- Automatic file validation and processing
Dispute Workflow
Step 1: List All Disputes
Use the List Disputes API to fetch disputes for your merchant account:
GET /underwriting/disputesCommon Query Parameters:
status: Filter by dispute status (OPEN, PENDING, WON, LOST, etc.)reason: Filter by dispute reason (FRAUD, TECHNICAL, CLERICAL, etc.)startDate/endDate: Filter by creation date rangesort: Sort by respond_by, created_at, updated_at, or status
Step 2: Identify Priority Disputes
Focus on disputes with:
- Status:
OPENorPENDING(require immediate attention) - Approaching
respond_bydeadlines - High-value transaction amounts
Step 1: Gather Supporting Documentation
Collect relevant evidence based on dispute reason:
- Fraud disputes: Transaction receipts, delivery confirmations, customer communications
- Authorization disputes: Signed agreements, authorization logs
- Processing disputes: Transaction records, refund documentation
Step 2: Upload Evidence Files
POST /file/dispute?dispute_id={id}&name={evidence_name}&file={file}Requirements:
- File size: Maximum 10MB
- Supported formats: .jpeg, .pdf, .png, .tiff
- Descriptive naming for easy identification
Step 3: Monitor Upload Status
Track evidence submission and ensure successful processing before response deadlines.
Real-time Updates
Set up webhook notifications to receive instant updates when:
- New disputes are created
- Dispute status changes occur
- Evidence upload confirmations
- Final resolution decisions
Status Tracking
Monitor dispute progression through these key statuses:
INQUIRY: Initial dispute investigationOPEN: Active dispute requiring responseEVIDENCE_UPLOADED: Evidence submitted for reviewWON: Dispute resolved in your favorLOST: Dispute resolved against youACCEPTED: Dispute accepted without contest
Dispute Statuses
Understanding Dispute Statuses
Active Statuses (Require Action):
INQUIRY: Preliminary dispute investigation - prepare evidenceOPEN: Active dispute requiring immediate responsePENDING: Awaiting decision after evidence submission
Processing Statuses:
EVIDENCE_UPLOADED: Evidence successfully submitted for reviewUPLOAD_FAILED: Evidence upload encountered errors - retry requiredPREARBITRATION: Escalated dispute requiring additional review
Final Statuses:
WON: Dispute resolved in your favor - no further action neededLOST: Dispute resolved against you - funds may be deductedACCEPTED: Dispute accepted without contest - refund processed
Best Practices
Monitor Deadlines
- Check
respond_bydates regularly - Set up automated alerts for approaching deadlines
- Respond as quickly as possible to improve success rates
Prioritize High-Impact Disputes
- Focus on high-value transactions first
- Address fraud-related disputes immediately
- Maintain organized evidence collection processes
Document Organization
- Use clear, descriptive file names
- Provide comprehensive supporting documentation
- Ensure all files are legible and properly formatted
Evidence Types by Dispute Reason
- Fraud: Delivery confirmations, customer ID verification
- Authorization: Signed agreements, approval codes
- Processing: Transaction logs, refund records
Integration Examples
Common Integration Patterns
Automated Dispute Monitoring:
// Check for new disputes daily
const checkDisputes = async () => {
const disputes = await fetch('/underwriting/disputes?status=OPEN');
const urgentDisputes = disputes.data.filter(d =>
new Date(d.respond_by) - new Date() < 48 * 60 * 60 * 1000 // 48 hours
);
if (urgentDisputes.length > 0) {
// Send alerts to dispute management team
notifyDisputeTeam(urgentDisputes);
}
};Bulk Evidence Upload:
// Upload multiple evidence files for a dispute
const uploadEvidence = async (disputeId, evidenceFiles) => {
const uploads = evidenceFiles.map(file =>
uploadFile(`/file/dispute`, {
dispute_id: disputeId,
name: file.name,
file: file.data
})
);
return Promise.all(uploads);
};