Skip to main content

​
Disputes

A Dispute is a formal challenge to a transaction. Disputes occur when a cardholder believes a transaction was unauthorized, incorrect, or the goods/services were not delivered.

​
What Triggers a Dispute

Disputes can be initiated for several reasons:
ReasonDescription
unauthorizedCardholder did not authorize the transaction
fraudSuspected fraudulent activity
not_receivedGoods or services were not received
not_as_describedProduct/service differs from what was described
duplicateCharged multiple times for the same purchase
incorrect_amountTransaction amount is wrong
canceledRecurring charge after cancellation
credit_not_processedRefund not received

​
Dispute Statuses

StatusDescription
openDispute filed, awaiting action
under_reviewEvidence submitted, being reviewed
resolvedDispute closed (won or lost)
wonDispute decided in cardholder’s favor
lostDispute decided in merchant’s favor

​
Dispute Lifecycle

Transaction Contested → open → Evidence Submitted → under_review → Resolved (won/lost)
Cardholder identifies an issue with a transaction and files a dispute.
  • Dispute is created with status open
  • Provisional credit may be issued
  • Merchant is notified

​
Filing a Dispute

​
Create a Dispute

curl -X POST https://api.useproxy.ai/v1/disputes \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_abc123",
    "reason": "not_received",
    "description": "Order never arrived despite tracking showing delivered"
  }'
Response: 
{
  "id": "dsp_xyz789",
  "transactionId": "txn_abc123",
  "customerId": "cust_xxx",
  "cardId": "card_yyy",
  "status": "open",
  "reason": "not_received",
  "description": "Order never arrived despite tracking showing delivered",
  "amount": 4500,
  "currency": "USD",
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Dispute Fields

FieldTypeDescription
transactionIdstringTransaction being disputed
reasonstringDispute reason code
descriptionstringDetailed explanation

​
Viewing Disputes

​
List All Disputes

curl https://api.useproxy.ai/v1/disputes \
  -H "Authorization: Bearer your_api_key"
Response: 
{
  "disputes": [
    {
      "id": "dsp_xyz789",
      "transactionId": "txn_abc123",
      "status": "under_review",
      "reason": "not_received",
      "amount": 4500,
      "currency": "USD",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Filter by Status

curl "https://api.useproxy.ai/v1/disputes?status=open" \
  -H "Authorization: Bearer your_api_key"

​
Get Single Dispute

curl https://api.useproxy.ai/v1/disputes/dsp_xyz789 \
  -H "Authorization: Bearer your_api_key"
Response: 
{
  "id": "dsp_xyz789",
  "transactionId": "txn_abc123",
  "customerId": "cust_xxx",
  "cardId": "card_yyy",
  "status": "under_review",
  "reason": "not_received",
  "description": "Order never arrived despite tracking showing delivered",
  "amount": 4500,
  "currency": "USD",
  "creditAmount": 4500,
  "evidence": {
    "submitted": true,
    "submittedAt": "2024-01-16T14:00:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T14:00:00Z"
}

​
Evidence Submission

Submit evidence to support a dispute claim.

​
Submit Text Evidence

curl -X POST https://api.useproxy.ai/v1/disputes/dsp_xyz789/evidence \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "textEvidence": "Order #12345 was placed on Jan 10. Tracking number 1Z999AA10123456784 shows delivered on Jan 12, but package was not at delivery location. Building security confirmed no package was received."
  }'

​
Submit Document Evidence

curl -X POST https://api.useproxy.ai/v1/disputes/dsp_xyz789/evidence \
  -H "Authorization: Bearer your_api_key" \
  -F "document=@tracking_screenshot.png" \
  -F "type=shipping_documentation"

​
Evidence Types

TypeDescription
receiptPurchase receipt or invoice
shipping_documentationTracking info, delivery confirmation
communicationEmails, chat logs with merchant
cancellation_proofCancellation confirmation
refund_policyMerchant refund/return policy
product_descriptionOriginal product listing
otherAny other relevant documentation

​
View Submitted Evidence

curl https://api.useproxy.ai/v1/disputes/dsp_xyz789/evidence \
  -H "Authorization: Bearer your_api_key"
Response: 
{
  "textEvidence": "Order #12345 was placed on Jan 10...",
  "documents": [
    {
      "id": "doc_001",
      "type": "shipping_documentation",
      "filename": "tracking_screenshot.png",
      "uploadedAt": "2024-01-16T14:00:00Z"
    }
  ]
}

​
Dispute Resolution

​
Checking Status

Disputes typically take 30-90 days to resolve. Check the status periodically: 
curl https://api.useproxy.ai/v1/disputes/dsp_xyz789 \
  -H "Authorization: Bearer your_api_key"

​
Resolution Outcomes

Won

The dispute was decided in your favor. The provisional credit becomes permanent.

Lost

The dispute was decided against you. The provisional credit is reversed.

​
Resolution Response

{
  "id": "dsp_xyz789",
  "status": "won",
  "reason": "not_received",
  "amount": 4500,
  "creditAmount": 4500,
  "resolution": {
    "outcome": "won",
    "resolvedAt": "2024-02-15T10:00:00Z",
    "notes": "Merchant unable to provide delivery confirmation"
  }
}

​
Dispute Webhooks

Subscribe to dispute events for real-time notifications:
EventDescription
dispute.createdNew dispute filed
dispute.updatedDispute status changed
dispute.resolvedDispute has been resolved

​
Webhook Payload

{
  "id": "evt_abc123",
  "type": "dispute.updated",
  "createdAt": "2024-01-20T10:30:00Z",
  "data": {
    "disputeId": "dsp_xyz789",
    "transactionId": "txn_abc123",
    "previousStatus": "open",
    "newStatus": "under_review",
    "reason": "not_received"
  }
}

​
Dispute Timeframes

PhaseTimeframe
Filing deadline60-120 days from transaction
Evidence submission7-20 days from dispute creation
Network review30-90 days
Second presentmentUp to 45 days (if applicable)
Disputes must be filed within the network-specified timeframe (typically 60-120 days from the transaction date). Late disputes may be automatically rejected.

​
Best Practices

Act Quickly

File disputes promptly and submit evidence within the deadline.

Document Everything

Save all receipts, communications, and delivery confirmations.

Be Specific

Provide detailed descriptions with dates, amounts, and order numbers.

Include Evidence

Submit screenshots, tracking info, and any supporting documents.

​
Dispute Prevention

Reduce disputes with proper intent matching and transaction monitoring: 
{
  "policy": {
    "requireIntent": true,
    "requireAttestation": true,
    "allowedMerchants": ["trusted-vendor.com"]
  }
}
  • Use requireIntent to ensure all transactions have documented purposes
  • Enable lockToFirstMerchant for subscription cards
  • Set appropriate spending limits with perAuth and perDay
  • Monitor transactions via webhooks and flag suspicious activity

​
Next Steps

Transactions

View transaction history

Policies

Configure spending controls

Webhooks

Get real-time notifications

Cards

Manage card settings