Disputes API

The Disputes API allows you to manage payment disputes (chargebacks) that customers file with their card issuing banks. When a customer disputes a charge, you can respond with evidence to contest the dispute.

Overview

Disputes occur when a customer questions a payment with their bank or credit card company. Common reasons include:

• Fraudulent transactions - Customer didn't authorize the payment
• Product not received - Customer claims they never received the goods/services
• Product unacceptable - Product was significantly different from description
• Duplicate charge - Customer was charged multiple times
• Credit not processed - Refund was promised but not received

Dispute Lifecycle

1. Open - Dispute filed by customer, funds withdrawn from your balance
2. Pending - You've submitted evidence, awaiting bank decision
3. Won - Dispute resolved in your favor, funds returned
4. Lost - Dispute resolved in customer's favor, funds permanently lost
5. Closed - Dispute closed (includes won/lost states)

Key Concepts

Dispute Status

• open - Awaiting your response with evidence
• pending - Evidence submitted, under review by issuing bank
• won - You won the dispute
• lost - You lost the dispute

Response Deadlines

• You typically have 14-21 days to respond with evidence
• Missing the deadline results in automatic loss
• Check charge_dispute_at date on the dispute object

Evidence Documents

Evidence strengthens your case. Upload documents such as:

• Proof of delivery (tracking numbers, signed receipts)
• Customer correspondence (emails, chat logs)
• Terms and conditions
• Product descriptions/photos
• Refund/cancellation policies

Available Endpoints

• List All Disputes - GET /disputes
• Retrieve a Dispute - GET /disputes/:id
• Update a Dispute - PATCH /disputes/:id
• List Closed Disputes - GET /disputes/closed
• List Open Disputes - GET /disputes/open
• List Pending Disputes - GET /disputes/pending
• Upload Document - POST /disputes/:id/documents

Best Practices

✅ Do This

• Respond quickly to disputes - don't wait until the deadline
• Provide comprehensive evidence - more documentation is better
• Keep detailed records - save all customer communications and delivery proof
• Set up webhooks to get notified immediately when disputes occur
• Use clear descriptions on charges to prevent confusion
• Provide excellent customer service to reduce dispute likelihood

❌ Don't Do This

• Don't ignore disputes - non-response results in automatic loss
• Don't provide irrelevant evidence - focus on addressing the dispute reason
• Don't assume you'll win - banks generally favor customers
• Don't wait for email notifications - use webhooks for real-time alerts

Webhook Events

Subscribe to these events to monitor disputes:

• charge.dispute.create - New dispute filed
• charge.dispute.update - Dispute status changed
• charge.dispute.close - Dispute closed (won or lost)

Related Resources

• Charges API
• Refunds API
• Webhooks Guide
• Dispute Management Guide

---

Need help? Contact support@omise.co for dispute assistance.