Disputes
A dispute (chargeback) occurs when a cardholder contests a transaction with their issuing bank. PerfectPay surfaces disputes in real time so you can respond quickly and submit evidence to fight illegitimate claims.
Dispute Lifecycle
opened --> challenged --> won
| +--> lost
+--> accepted
+--> cancelled
+--> expired
| Status | Meaning |
|---|---|
dispute_opened | The issuer has initiated a dispute; action is required |
dispute_accepted | You accepted the dispute and agreed to the chargeback |
dispute_cancelled | The dispute was withdrawn by the issuer or cardholder |
dispute_challenged | You submitted evidence to contest the dispute |
dispute_won | The issuer ruled in your favor after reviewing evidence |
dispute_lost | The issuer ruled in the cardholder's favor |
dispute_expired | The response window closed without action |
List Disputes
GET /disputes/list
curl https://sandbox.perfectpay.ai/disputes/list \
-H "api-key: YOUR_SECRET_API_KEY"
Filter by status, date range, or payment ID for reconciliation.
Retrieve a Dispute
GET /disputes/{dispute_id}
curl https://sandbox.perfectpay.ai/disputes/dis_abc123 \
-H "api-key: YOUR_SECRET_API_KEY"
Accept a Dispute
POST /disputes/accept/{dispute_id}
Accept the dispute when the chargeback is legitimate and you do not want to contest it.
curl https://sandbox.perfectpay.ai/disputes/accept/dis_abc123 \
-X POST \
-H "api-key: YOUR_SECRET_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
Submit Evidence
POST /disputes/evidence
Challenge a dispute by submitting evidence that the transaction was legitimate.
curl https://sandbox.perfectpay.ai/disputes/evidence \
-X POST \
-H "api-key: YOUR_SECRET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dispute_id": "dis_abc123",
"evidence": {
"customer_name": "Jane Doe",
"customer_email": "[email protected]",
"product_description": "Premium subscription - 12 months",
"receipt": "Receipt #1001, charged on 2026-03-15",
"shipping_tracking_number": "1Z999AA10123456784",
"refund_policy_disclosure": "https://example.com/refund-policy",
"uncategorized_text": "Customer confirmed delivery via email on 2026-03-18"
}
}'
Submit as much evidence as possible. Common evidence types:
- Customer communication showing the cardholder acknowledged the purchase
- Delivery tracking and proof of receipt
- Signed contracts or terms of service acceptance
- Refund policy disclosure
- Product or service descriptions
Webhook Events
PerfectPay sends webhook events for each dispute status change. Subscribe to these events to automate your dispute response workflow.
| Event | When it fires |
|---|---|
dispute_opened | A new dispute is created |
dispute_accepted | You accepted the dispute |
dispute_challenged | You submitted evidence |
dispute_won | The issuer ruled in your favor |
dispute_lost | The issuer ruled against you |
dispute_expired | The response window closed |
dispute_cancelled | The dispute was withdrawn |
See the Webhooks guide for setup and handling instructions.
Preventing Disputes
The best dispute strategy is prevention. Reduce chargeback rates with these practices:
- Clear billing descriptors -- make sure the charge description on the cardholder's statement is recognizable
- Prompt refunds -- issue refunds quickly when requested instead of forcing customers to dispute
- Delivery confirmation -- collect proof of delivery for physical goods
- Customer communication -- send order confirmations, shipping notifications, and receipts
- Fraud prevention -- use fraud detection tools to block illegitimate transactions before they settle
- 3DS authentication -- shift liability to the issuer for 3DS-authenticated transactions (see 3DS Authentication)
Operational Notes
- Respond to disputes within the window specified by the card network (typically 7-30 days depending on the reason code)
- Track your dispute rate in the dashboard under Analytics -- card networks penalize merchants with dispute rates above 1%
- Automate evidence collection using webhooks and your order management system