Disputes Rail

Disputes Rail

Dispute resolution, case management, and escalation workflows.

Overview

The Disputes Rail provides endpoints for managing customer disputes, resolution workflows, and escalation processes.

Base URL

/api/v1/disputes

Endpoints

Create Dispute

POST /api/v1/disputes

Create a new dispute.

Request Body:

{
  "type": "TRANSACTION",
  "category": "UNAUTHORIZED_TRANSACTION",
  "customerId": "cust_123",
  "transactionId": "txn_abc",
  "amount": "5000.00",
  "currency": "SAR",
  "description": "Customer claims transaction was not authorized",
  "evidence": ["doc_123", "doc_456"],
  "priority": "HIGH"
}

Response:

{
  "data": {
    "disputeId": "dsp_abc123",
    "caseNumber": "DSP-2025-0001",
    "status": "OPEN",
    "assignedTo": "agent_xyz",
    "slaDeadline": "2025-01-25T10:00:00Z",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Get Dispute

GET /api/v1/disputes/:disputeId

Retrieve dispute details.

List Disputes

GET /api/v1/disputes

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
category	string	Filter by category
priority	string	Filter by priority
assignedTo	string	Filter by assignee
customerId	string	Filter by customer

Update Dispute

PATCH /api/v1/disputes/:disputeId

Update dispute details.

Request Body:

{
  "status": "INVESTIGATING",
  "notes": "Contacted merchant for transaction details"
}

Add Comment

POST /api/v1/disputes/:disputeId/comments

Add a comment to the dispute.

Request Body:

{
  "content": "Merchant confirmed transaction was legitimate",
  "internal": true,
  "attachments": ["doc_789"]
}

Escalate Dispute

POST /api/v1/disputes/:disputeId/escalate

Escalate to higher authority.

Request Body:

{
  "reason": "Customer unsatisfied with initial resolution",
  "escalateTo": "SUPERVISOR",
  "notes": "Requires senior review"
}

Resolve Dispute

POST /api/v1/disputes/:disputeId/resolve

Resolve the dispute.

Request Body:

{
  "resolution": "CUSTOMER_FAVOR",
  "action": "REFUND",
  "amount": "5000.00",
  "notes": "Merchant unable to provide authorization proof",
  "compensation": {
    "type": "GOODWILL",
    "amount": "100.00"
  }
}

Get Dispute Timeline

GET /api/v1/disputes/:disputeId/timeline

Get dispute activity timeline.

Response:

{
  "data": [
    {
      "timestamp": "2025-01-15T10:00:00Z",
      "event": "CREATED",
      "actor": "cust_123",
      "details": "Dispute opened via mobile app"
    },
    {
      "timestamp": "2025-01-15T10:05:00Z",
      "event": "ASSIGNED",
      "actor": "system",
      "details": "Auto-assigned to agent_xyz"
    }
  ]
}

Dispute Types

Type	Description
TRANSACTION	Transaction dispute
BILLING	Billing dispute
SERVICE	Service quality dispute
CONTRACT	Contract dispute
FEE	Fee dispute

Dispute Categories

Category	Description
UNAUTHORIZED_TRANSACTION	Unauthorized transaction
DUPLICATE_CHARGE	Duplicate charge
INCORRECT_AMOUNT	Incorrect amount
NOT_RECEIVED	Product/service not received
QUALITY_ISSUE	Quality issue
CANCELLATION	Cancellation dispute

Resolution Types

Resolution	Description
CUSTOMER_FAVOR	Resolved in customer favor
MERCHANT_FAVOR	Resolved in merchant favor
PARTIAL	Partial resolution
WITHDRAWN	Customer withdrew dispute
EXPIRED	Dispute expired

Priority Levels

Priority	SLA
CRITICAL	4 hours
HIGH	24 hours
MEDIUM	3 days
LOW	7 days

Events

Event	Description
dispute.created	Dispute created
dispute.assigned	Dispute assigned
dispute.escalated	Dispute escalated
dispute.resolved	Dispute resolved
dispute.sla.breach	SLA breached

See Also

• Cases Rail - Case management
• Compliance Rail - Compliance checks