Skip to main content
A dispute is a formal challenge against a settled transaction. Useful when goods don’t arrive, the merchant overcharges, or the agent paid for something unauthorized despite the policy. Each transaction can have at most one open dispute. Dispute lifecycle is plan-tier-gated.

​
Reason codes

CodeMeaning
unauthorizedSpend wasn’t authorized by policy
fraudSuspected fraudulent transaction
not_receivedGoods or service never delivered
not_as_describedDelivered but doesn’t match agreement
duplicateCharged more than once
incorrect_amountAmount differs from agreed price
canceledCancelled but still charged
credit_not_processedRefund wasn’t applied

​
File a dispute

curl -X POST https://api.getovra.com/disputes \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "transactionId": "tx_...",
    "reason": "not_received",
    "description": "Order placed 10 days ago, tracking shows no movement"
  }'
Response: 
{
  "id": "dsp_...",
  "transactionId": "tx_...",
  "reason": "not_received",
  "status": "open",
  "createdAt": "2026-04-20T12:34:56Z"
}

​
Attach evidence

curl -X POST https://api.getovra.com/disputes/dsp_.../evidence \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "communication",
    "description": "Email thread with merchant support",
    "fileUrl": "https://storage.example.com/evidence/abc.pdf"
  }'
Evidence types: receipt · shipping · communication · cancellation · refund_policy · product_description · other. File URLs must be HTTPS and SSRF-safe (no private IPs).

​
Resolve

curl -X PATCH https://api.getovra.com/disputes/dsp_... \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{ "status": "resolved" }'
Set status to resolved or rejected. Once closed, no further mutation is allowed.

​
Webhooks

EventWhen
dispute.createdFiled
dispute.updatedEvidence added or fields changed
dispute.resolvedClosed (resolved or rejected)

​
Plan-tier gating

PlanDispute management
Free–
StarterView only
BusinessFull (file + manage + resolve)
EnterpriseFull + automated workflows

​
Surfaces

SurfaceCapability
REST/disputes, /disputes/:id/evidence
SDKovra.disputes.*
MCPovra_dispute (action: get · file)
Dashboard/dashboard/disputes

​
Next

Transactions

What you’re disputing.

Intelligence

Audit trail and access events for dispute investigations.