Handle Disputes

Create incidents, investigate, and resolve through governance

Dispute Lifecycle

Valid state transitions for dispute resolution

openinvestigatingInvestigation starts

investigatingresolvedResolution approved

investigatingescalatedManual review required

escalatedresolvedAdmin resolves

Create a Dispute

File a dispute against a transaction

curl -X POST https://api.sandbox.zexrail.com/v1/governance/disputes \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "negotiation_id": "neg_xyz",
    "reason": "Settlement amount does not match agreed terms",
    "evidence": {
      "expected_amount": 5000,
      "received_amount": 4000
    }
  }'

Investigate the Dispute

Verity runs an automatic investigation

curl https://api.sandbox.zexrail.com/v1/governance/disputes/{dispute_id} \
  -H "Authorization: Bearer sk_test_your_key"

Resolve the Dispute

Approve or reject the proposed resolution

curl -X POST https://api.sandbox.zexrail.com/v1/governance/disputes/{dispute_id}/resolve \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "refund",
    "amount": 1000,
    "note": "Partial refund for discrepancy"
  }'

Next Steps