Disputes

Payment dispute management. All endpoints require authentication.

GET /disputes

List disputes for the authenticated user.

curl "https://api.paylinks.ro/api/v1/disputes?status=needs_response&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

Parameter	Type	Default	Description
limit	integer	20	Items per page
offset	integer	0	Pagination offset
status	string	—	Filter: needs_response, under_review, won, lost, closed

Response (200):

{
  "disputes": [
    {
      "id": "disp-001",
      "transactionId": "tx-001",
      "stripeDisputeId": "dp_1234567890",
      "amount": 4999,
      "currency": "RON",
      "status": "needs_response",
      "reason": "fraudulent",
      "evidenceDueBy": "2026-03-01T00:00:00.000Z",
      "createdAt": "2026-02-15T10:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Dispute Statuses

Status	Description
needs_response	New dispute, evidence can be submitted
under_review	Evidence submitted, awaiting Stripe decision
won	Dispute resolved in seller's favor
lost	Dispute resolved in buyer's favor
closed	Dispute closed on Stripe

---

GET /disputes/:id

Get a single dispute by ID.

curl https://api.paylinks.ro/api/v1/disputes/disp-001 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200): Full dispute object. Response shape:

{
  "dispute": {
    "id": "disp-001",
    "status": "needs_response"
  }
}

---

POST /disputes/:id/evidence

Submit evidence for a dispute.

curl -X POST https://api.paylinks.ro/api/v1/disputes/disp-001/evidence \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "John Doe",
    "customerEmail": "[email protected]",
    "productDescription": "Digital product delivered instantly",
    "sellerNotes": "Customer downloaded assets before opening dispute",
    "fileKeys": ["users/u_123/disputes/disp_001/evidence.pdf"]
  }'

Request Body:

Field	Type	Required	Description
customerName	string	No	Buyer's full name
customerEmail	string	No	Buyer's email
productDescription	string	No	What was delivered
shippingCarrier	string	No	Carrier used for physical delivery
shippingTrackingNumber	string	No	Tracking number
shippingDate	date-time	No	Shipping date
serviceDate	date-time	No	Service delivery date
sellerNotes	string	No	Additional seller context
fileKeys	string[]	No	R2 private keys for uploaded evidence files

Response (200):

{"success": true}