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:

Reason	Description
`unauthorized`	Cardholder did not authorize the transaction
`fraud`	Suspected fraudulent activity
`not_received`	Goods or services were not received
`not_as_described`	Product/service differs from what was described
`duplicate`	Charged multiple times for the same purchase
`incorrect_amount`	Transaction amount is wrong
`canceled`	Recurring charge after cancellation
`credit_not_processed`	Refund not received

Dispute Statuses

Status	Description
`open`	Dispute filed, awaiting action
`under_review`	Evidence submitted, being reviewed
`resolved`	Dispute closed (won or lost)
`won`	Dispute decided in cardholder’s favor
`lost`	Dispute decided in merchant’s favor

Dispute Lifecycle

Transaction Contested → open → Evidence Submitted → under_review → Resolved (won/lost)

Phase 1: Filing
Phase 2: Evidence
Phase 3: Review
Phase 4: Resolution

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

The card network reviews the evidence and makes a determination.

Status changes to under_review
Typical review period: 30-90 days
Additional information may be requested

The dispute is resolved in favor of either the cardholder or merchant.

won: Cardholder keeps the credit
lost: Credit is reversed; funds returned to merchant

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

Field	Type	Description
`transactionId`	string	Transaction being disputed
`reason`	string	Dispute reason code
`description`	string	Detailed 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

Type	Description
`receipt`	Purchase receipt or invoice
`shipping_documentation`	Tracking info, delivery confirmation
`communication`	Emails, chat logs with merchant
`cancellation_proof`	Cancellation confirmation
`refund_policy`	Merchant refund/return policy
`product_description`	Original product listing
`other`	Any 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:

Event	Description
`dispute.created`	New dispute filed
`dispute.updated`	Dispute status changed
`dispute.resolved`	Dispute 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

Phase	Timeframe
Filing deadline	60-120 days from transaction
Evidence submission	7-20 days from dispute creation
Network review	30-90 days
Second presentment	Up 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

Getting Started

Concepts

Disputes

Disputes

What Triggers a Dispute

Dispute Statuses

Dispute Lifecycle

Filing a Dispute

Create a Dispute

Dispute Fields

Viewing Disputes

List All Disputes

Filter by Status

Get Single Dispute

Evidence Submission

Submit Text Evidence

Submit Document Evidence

Evidence Types

View Submitted Evidence

Dispute Resolution

Checking Status

Resolution Outcomes

Won

Lost

Resolution Response

Dispute Webhooks

Webhook Payload

Dispute Timeframes

Best Practices

Act Quickly

Document Everything

Be Specific

Include Evidence

Dispute Prevention

Next Steps

Transactions

Policies

Webhooks

Cards

​Disputes

​What Triggers a Dispute

​Dispute Statuses

​Dispute Lifecycle

​Filing a Dispute

​Create a Dispute

​Dispute Fields

​Viewing Disputes

​List All Disputes

​Filter by Status

​Get Single Dispute

​Evidence Submission

​Submit Text Evidence

​Submit Document Evidence

​Evidence Types

​View Submitted Evidence

​Dispute Resolution

​Checking Status

​Resolution Outcomes

Won

Lost

​Resolution Response

​Dispute Webhooks

​Webhook Payload

​Dispute Timeframes

​Best Practices

Act Quickly

Document Everything

Be Specific

Include Evidence

​Dispute Prevention

​Next Steps

Transactions

Policies

Webhooks

Cards

Disputes

What Triggers a Dispute

Dispute Statuses

Dispute Lifecycle

Filing a Dispute

Create a Dispute

Dispute Fields

Viewing Disputes

List All Disputes

Filter by Status

Get Single Dispute

Evidence Submission

Submit Text Evidence

Submit Document Evidence

Evidence Types

View Submitted Evidence

Dispute Resolution

Checking Status

Resolution Outcomes

Resolution Response

Dispute Webhooks

Webhook Payload

Dispute Timeframes

Best Practices

Dispute Prevention

Next Steps