Overview
Disputes occur when a cardholder contests a transaction with their issuing bank. Yuno provides a unified Disputes API to track, respond to, and manage chargebacks across all your payment providers. Timely and well-documented responses are critical to winning disputes and protecting your revenue.
Dispute Lifecycle
| Status | Description | Merchant Action |
|---|
OPEN | Dispute filed by cardholder | Review and prepare evidence |
UNDER_REVIEW | Evidence submitted, awaiting decision | Monitor for updates |
WON | Dispute resolved in merchant’s favor | Funds returned to merchant |
LOST | Dispute resolved in cardholder’s favor | Funds debited from merchant |
EXPIRED | Response deadline passed without action | Automatic loss, funds debited |
Each dispute has a strict response deadline (typically 7-30 days depending on the card network). Failing to respond before the deadline results in an automatic loss.
Viewing Disputes
List All Disputes
curl --request GET \
--url https://api.y.uno/v1/disputes \
--header 'X-Api-Key: YOUR_API_KEY'
Get Dispute Details
curl --request GET \
--url https://api.y.uno/v1/disputes/dsp_abc123 \
--header 'X-Api-Key: YOUR_API_KEY'
{
"id": "dsp_abc123",
"payment_id": "pay_xyz789",
"status": "OPEN",
"reason": "FRAUDULENT",
"amount": {
"value": 250.00,
"currency": "USD"
},
"deadline": "2026-03-15T23:59:59Z",
"created_at": "2026-02-28T10:00:00Z"
}
Dispute Reason Codes
| Reason | Description | Common Evidence |
|---|
FRAUDULENT | Cardholder claims unauthorized use | 3DS proof, IP logs, delivery confirmation |
PRODUCT_NOT_RECEIVED | Customer did not receive goods | Shipping tracking, delivery proof |
PRODUCT_UNACCEPTABLE | Product/service not as described | Terms of service, product description |
DUPLICATE | Customer charged more than once | Transaction logs showing single charge |
SUBSCRIPTION_CANCELLED | Charged after cancellation | Cancellation policy, cancellation timestamp |
CREDIT_NOT_PROCESSED | Refund promised but not received | Refund records, communication logs |
Submitting Evidence
Respond to a dispute by submitting evidence before the deadline.
curl --request POST \
--url https://api.y.uno/v1/disputes/dsp_abc123/evidence \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
"evidence_type": "COMPELLING_EVIDENCE",
"description": "Customer authenticated via 3DS 2.0. Delivery confirmed.",
"documents": [
{
"type": "DELIVERY_PROOF",
"url": "https://yourdomain.com/evidence/delivery_proof.pdf"
},
{
"type": "TRANSACTION_LOG",
"url": "https://yourdomain.com/evidence/3ds_auth_log.pdf"
}
]
}'
Provide as much relevant evidence as possible in a single submission. Multiple submissions may not be allowed depending on the card network’s dispute process.
Webhook Events
| Event | Trigger |
|---|
dispute.created | New dispute filed |
dispute.updated | Dispute status changed |
dispute.won | Resolved in merchant’s favor |
dispute.lost | Resolved in cardholder’s favor |
dispute.deadline_approaching | Response deadline within 48 hours |
Best Practices
- Respond promptly: Submit evidence well before the deadline. Do not wait until the last day.
- Use 3D Secure: Transactions authenticated with 3DS benefit from liability shift, which can resolve disputes in your favor automatically.
- Keep records: Maintain delivery confirmations, customer communications, and transaction logs.
- Monitor
dispute.created webhooks: Set up alerts for immediate notification of new disputes.
- Track dispute rates: A dispute rate above 1% can trigger card network monitoring programs.
You can also manage disputes through the Yuno Dashboard under Payments > Disputes, which provides a visual interface for reviewing dispute details and uploading evidence.
