06 disputes

Disputes allow buyers and merchants to resolve payment conflicts. Funds remain in escrow until the dispute is resolved.

Dispute Lifecycle

open → pending_merchant → pending_buyer → under_review → resolved
                                                      ↘ closed

Status	Description
open	Dispute opened, awaiting merchant response
pending_merchant	Waiting for merchant evidence
pending_buyer	Waiting for buyer response
under_review	Admin reviewing evidence
resolved	Decision made, funds distributed
closed	Dispute withdrawn or expired

Dispute Timeline

Event	Deadline
Merchant response	3 days from opening
Evidence submission	7 days from opening
Resolution	14 days from opening

---

Open Dispute

Buyers can open disputes for paid invoices within the buffer period.

POST /disputes/open

Request

{
  "invoice_id": "inv_abc123",
  "reason": "product_not_received",
  "description": "I paid for the product 5 days ago but never received it. The merchant is not responding to my emails.",
  "buyer_email": "[email protected]",
  "evidence": [
    {
      "type": "text",
      "content": "Order confirmation email shows delivery was promised within 3 days."
    },
    {
      "type": "link",
      "content": "https://example.com/screenshot-of-order"
    }
  ]
}

Parameters

Field	Type	Required	Description
invoice_id	string	✓	Invoice to dispute
reason	string	✓	Reason code (see below)
description	string	✓	Detailed explanation
buyer_email	string		Email for updates
evidence	array		Supporting evidence

Reason Codes

Code	Description
product_not_received	Never received the product/service
product_not_as_described	Product differs from description
unauthorized_transaction	Didn't authorize this payment
duplicate_charge	Charged multiple times
other	Other reason

Response

{
  "success": true,
  "data": {
    "dispute_id": "dis_abc123def456",
    "invoice_id": "inv_abc123",
    "amount": 99.99,
    "currency": "USDC",
    "chain": "solana",
    "status": "open",
    "reason": "product_not_received",
    "deadlines": {
      "merchant_response": "2024-01-18T11:00:00Z",
      "evidence": "2024-01-22T11:00:00Z",
      "resolution": "2024-01-29T11:00:00Z"
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Dispute

GET /disputes/:disputeId

Response

{
  "success": true,
  "data": {
    "dispute_id": "dis_abc123",
    "invoice_id": "inv_abc123",
    "merchant_id": "mer_xyz789",
    "amount": 99.99,
    "currency": "USDC",
    "chain": "solana",
    "status": "pending_merchant",
    "reason": "product_not_received",
    "description": "I paid for the product 5 days ago...",
    "buyer_wallet": "buyer_wallet_address",
    "buyer_email": "[email protected]",
    "buyer_evidence": [
      {
        "type": "text",
        "content": "Order confirmation email...",
        "submitted_at": "2024-01-15T11:00:00Z"
      }
    ],
    "merchant_evidence": [],
    "deadlines": {
      "merchant_response": "2024-01-18T11:00:00Z",
      "evidence": "2024-01-22T11:00:00Z",
      "resolution": "2024-01-29T11:00:00Z"
    },
    "status_history": [
      {
        "status": "open",
        "timestamp": "2024-01-15T11:00:00Z"
      }
    ],
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

List Disputes

GET /disputes

Query Parameters

Parameter	Type	Description
status	string	Filter by status
invoice_id	string	Filter by invoice
page	number	Page number
limit	number	Items per page

Response

{
  "success": true,
  "data": [
    {
      "dispute_id": "dis_abc123",
      "invoice_id": "inv_abc123",
      "amount": 99.99,
      "status": "open",
      "reason": "product_not_received",
      "deadlines": {
        "merchant_response": "2024-01-18T11:00:00Z"
      },
      "created_at": "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

---

Submit Evidence (Merchant)

Submit evidence to support your case.

POST /disputes/:disputeId/evidence

Request (multipart/form-data)

Field	Type	Description
files	file[]	Evidence files (max 5, max 10MB each)
description	string	Text explanation
links	string[]	Supporting URLs

Example (cURL)

curl -X POST https://api.stablix.xyz/api/v1/disputes/dis_abc123/evidence \
  -H "Authorization: Bearer your_token" \
  -F "files=@shipping_confirmation.pdf" \
  -F "files=@delivery_photo.jpg" \
  -F "description=Package was delivered on Jan 12. Attached is the shipping confirmation and delivery photo." \
  -F "links[]=https://tracking.ups.com/12345"

Response

{
  "success": true,
  "message": "Evidence submitted",
  "data": {
    "dispute_id": "dis_abc123",
    "evidence_count": 3,
    "status": "pending_buyer"
  }
}

---

Accept Dispute (Merchant)

Accept the dispute and agree to refund the buyer.

POST /disputes/:disputeId/accept

Response

{
  "success": true,
  "message": "Dispute accepted, refund initiated",
  "data": {
    "dispute_id": "dis_abc123",
    "status": "resolved",
    "resolution": {
      "decision": "buyer_wins",
      "buyer_amount": 98.99,
      "merchant_amount": 0,
      "fee_amount": 1.00,
      "tx_hash": "refund_tx_hash..."
    }
  }
}

---

Submit Buyer Evidence

Buyers submit additional evidence through the public endpoint.

POST /disputes/:disputeId/buyer-evidence

Request (multipart/form-data)

Field	Type	Description
files	file[]	Evidence files
description	string	Text explanation

---

Resolution Outcomes

When a dispute is resolved by admin:

Buyer Wins

• Buyer receives: Full amount minus dispute fee

• Merchant receives: Nothing

• Fee: 1% of transaction

Merchant Wins

• Buyer receives: Nothing

• Merchant receives: Full amount minus dispute fee

• Fee: 1% of transaction

Split Decision

• Funds split according to admin decision

• Both parties receive proportional amounts minus fees

---

Dispute Fees

Fee	Amount
Dispute resolution	1% of transaction

The fee is deducted from the losing party's amount (or split in split decisions).

---

Dispute Webhooks

Event	Description
dispute.opened	New dispute created
dispute.evidence_submitted	Evidence added
dispute.status_changed	Status updated
dispute.resolved	Dispute resolved
dispute.closed	Dispute closed/withdrawn

Example Webhook Payload

{
  "event": "dispute.resolved",
  "data": {
    "dispute_id": "dis_abc123",
    "invoice_id": "inv_abc123",
    "status": "resolved",
    "resolution": {
      "decision": "merchant_wins",
      "buyer_amount": 0,
      "merchant_amount": 98.99,
      "fee_amount": 1.00
    }
  },
  "timestamp": "2024-01-25T11:00:00Z"
}

---

Best Practices

For Merchants

1. Respond quickly — You have 3 days to respond to disputes.

2. Provide clear evidence — Shipping confirmations, delivery proofs, communication logs.

3. Keep records — Store all transaction-related documentation.

4. Communicate with buyers — Many disputes can be resolved directly.

5. Accept when appropriate — If the buyer has a valid claim, accepting saves time and fees.

For Buyers

1. Contact merchant first — Try to resolve directly before disputing.

2. Provide detailed description — Explain exactly what happened.

3. Include evidence — Screenshots, emails, order confirmations.

4. Respond to requests — Check for messages from Stablix support.

---

Preventing Disputes

1. Set appropriate buffer periods — Longer buffers for physical goods.

2. Send tracking information — Update customers on delivery status.

3. Clear product descriptions — Accurate listings reduce "not as described" claims.

4. Responsive support — Quick responses prevent escalation.

5. Clear refund policy — Publish and follow a fair refund policy.