06 disputes

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

Buyer Protection

Every Stablix payment is protected. Buyers can open disputes using email verification - no wallet connection required. This is perfect for users who paid from centralized exchanges (Coinbase, Binance, etc.).

How to Open a Dispute

Option 1: Direct Link (Recommended)

Visit the dispute page for your specific invoice:

https://stablix.xyz/dispute/:invoiceId

You'll need:

• The invoice ID from your payment receipt

• Access to the email associated with the invoice

Option 2: Through Merchant

If the merchant has integrated disputes, use their dispute flow.

Note: Disputes can only be opened while funds are still in escrow (during the buffer period). Once funds are released to the merchant, disputes are no longer available.

---

Dispute Lifecycle

open → pending_merchant → pending_buyer → under_review → resolved
                                                      ↘ closed

Dispute Timeline

Stage	Duration	Description
Merchant Response	3 days	Merchant has 3 days to respond with counter-evidence
Admin Review	Up to 14 days	Stablix team reviews all evidence and makes a decision
Resolution	Immediate	Decision executed on blockchain, funds distributed

---

Email Verification Flow

Buyers verify their identity using a magic code sent to their email. This allows users who paid from CEX wallets to open disputes without connecting a wallet.

Step 1: Request Verification Code

The buyer enters the email address associated with the invoice. A 6-digit verification code is sent to that email.

POST /dispute/buyer/request-code

Request Body:

{
  "invoice_id": "inv_abc123",
  "email": "[email protected]"
}

Response:

{
  "success": true,
  "message": "Check your email for the verification code"
}

Security:

• Code expires in 10 minutes

• Email must match the invoice customer email

• Rate limited to 3 requests per hour per IP

• Rate limited to 5 requests per hour per email

Errors:

• 400 - Invalid email format

• 401 - Email doesn't match invoice

• 404 - Invoice not found

• 429 - Too many requests (rate limit exceeded)

---

Step 2: Open Dispute with Code

After receiving the verification code, the buyer submits their dispute along with the code for verification.

POST /dispute/buyer/open-with-code

Request (JSON):

{
  "invoice_id": "inv_abc123",
  "code": "123456",
  "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."
}

Request (multipart/form-data with file):

curl -X POST https://api.stablix.xyz/api/v1/dispute/buyer/open-with-code \
  -F "invoice_id=inv_abc123" \
  -F "code=123456" \
  -F "reason=product_not_received" \
  -F "description=I paid for the product 5 days ago..." \
  -F "evidence=@receipt_screenshot.png"

Parameters:

Field	Type	Required	Description
invoice_id	string	Yes	The invoice to dispute
code	string	Yes	6-digit verification code from email
reason	string	Yes	Dispute reason (see reason codes below)
description	string	Yes	Detailed explanation (min 20 characters)
evidence	file	No	Supporting file (JPG/PNG/PDF, max 5MB)

Reason Codes:

Code	Description
not_received	Item/Service Not Received
not_as_described	Item/Service Not as Described
duplicate_payment	Duplicate Payment
unauthorized	Unauthorized Transaction
quality_issues	Quality Issues
other	Other

Response:

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

Success Response Details:

• dispute_id - Unique dispute identifier

• tx_hash - Blockchain transaction hash (proof of dispute opening)

• deadlines - Important dates for the dispute process

• status - Current dispute status (pending_merchant)

Blockchain Integration:

• The dispute is automatically recorded on the blockchain

• The platform wallet signs the transaction (no wallet connection needed)

• Transaction typically takes 5-10 seconds

• Provides transparent, immutable proof of the dispute

Errors:

• 400 - Invalid code or missing required fields

• 401 - Code expired or invalid (codes expire in 10 minutes)

• 404 - Invoice not found

• 409 - Dispute already exists or buffer period expired

• 500 - Blockchain transaction failed

---

API Key Routes (Merchant)

Merchants can manage disputes programmatically using their API key.

Authentication

Include your API key in the request header:

X-API-Key: your_api_key_here

---

List Disputes

Get a paginated list of disputes for your account.

GET /disputes

Query Parameters:

Parameter	Type	Default	Description
status	string	-	Filter by status (optional)
page	number	1	Page number
limit	number	20	Results per page (max 100)

Example Request:

curl https://api.stablix.xyz/api/v1/disputes?status=pending_merchant&page=1&limit=20 \
  -H "X-API-Key: your_api_key"

Response:

{
  "success": true,
  "data": [
    {
      "dispute_id": "dis_abc123",
      "invoice_id": "inv_abc123",
      "amount": 99.99,
      "currency": "USDC",
      "chain": "solana",
      "status": "pending_merchant",
      "reason": "product_not_received",
      "opened_by": "buyer",
      "buyer_email": "[email protected]",
      "deadlines": {
        "merchant_response": "2024-01-18T11:00:00Z",
        "resolution": "2024-01-29T11:00:00Z"
      },
      "created_at": "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3,
    "hasMore": true
  }
}

---

Get Dispute Details

Get detailed information about a specific dispute, including all evidence.

GET /disputes/:disputeId

Example Request:

curl https://api.stablix.xyz/api/v1/disputes/dis_abc123 \
  -H "X-API-Key: your_api_key"

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 but never received it...",
    "opened_by": "buyer",
    "buyer_wallet": "buyer_wallet_address",
    "buyer_email": "[email protected]",
    "evidence": {
      "buyer": [
        {
          "type": "text",
          "content": "Order confirmation shows delivery within 3 days",
          "submitted_at": "2024-01-15T11:00:00Z"
        },
        {
          "type": "file",
          "content": "receipt_screenshot.png",
          "file_key": "disputes/dis_abc123/buyer/file1.png",
          "submitted_at": "2024-01-15T11:00:00Z"
        }
      ],
      "merchant": []
    },
    "deadlines": {
      "merchant_response": "2024-01-18T11:00:00Z",
      "buyer_response": null,
      "resolution": "2024-01-29T11:00:00Z"
    },
    "status_history": [
      {
        "status": "open",
        "timestamp": "2024-01-15T11:00:00Z",
        "by": "buyer"
      },
      {
        "status": "pending_merchant",
        "timestamp": "2024-01-15T11:00:00Z",
        "by": "buyer"
      }
    ],
    "created_at": "2024-01-15T11:00:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

Evidence Types:

• text - Text description or notes

• file - Uploaded file (image or PDF)

• link - External URL

---

Submit Evidence (Merchant)

Submit evidence to support your case against a dispute.

POST /disputes/:disputeId/evidence

Request (multipart/form-data):

Field	Type	Required	Description
type	string	Yes	Evidence type: text, file, or link
content	string	Yes	Text content, file name, or URL
file	file	No	File upload (required if type is file)

Example Request:

curl -X POST https://api.stablix.xyz/api/v1/disputes/dis_abc123/evidence \
  -H "X-API-Key: your_api_key" \
  -F "type=file" \
  -F "content=Shipping confirmation and delivery proof" \
  -F "file=@shipping_confirmation.pdf"

Response:

{
  "success": true,
  "message": "Evidence submitted successfully",
  "data": {
    "dispute_id": "dis_abc123",
    "status": "pending_buyer",
    "evidence_count": 2,
    "deadlines": {
      "buyer_response": "2024-01-21T11:00:00Z",
      "resolution": "2024-01-29T11:00:00Z"
    }
  }
}

Status Transitions:

• When merchant submits first evidence: pending_merchant → pending_buyer

• When buyer submits response: pending_buyer → under_review

File Requirements:

• Formats: JPG, PNG, WEBP, PDF

• Max size: 10MB per file

• Stored securely in S3 with signed URLs

Errors:

• 400 - Invalid file type or missing required fields

• 404 - Dispute not found

• 409 - Dispute already resolved

• 413 - File too large

---

Resolution Outcomes

When a dispute is resolved by the Stablix admin team:

Buyer Wins

• Buyer receives: Full amount minus dispute fee

• Merchant receives: Nothing

• Fee: 1% of transaction amount

Merchant Wins

• Buyer receives: Nothing

• Merchant receives: Full amount minus dispute fee

• Fee: 1% of transaction amount

Split Decision

• Funds split according to admin decision

• Both parties receive proportional amounts minus fees

• Admin can specify exact percentage split

Example Split:

{
  "decision": "split",
  "buyer_percentage": 60,
  "merchant_percentage": 40,
  "buyer_amount": 59.40,
  "merchant_amount": 39.60,
  "fee_amount": 1.00
}

---

Dispute Fees

Scenario	Fee Amount	Deducted From
Buyer Wins	1% of transaction	Merchant's payout (0%)
Merchant Wins	1% of transaction	Buyer's refund (0%)
Split Decision	1% of transaction	Split between both parties

The fee is automatically deducted when the dispute is resolved on the blockchain.

---

Dispute Webhooks

Receive real-time notifications when dispute status changes.

Events

Event	Description
dispute.opened	New dispute opened
dispute.evidence_submitted	Evidence added by either party
dispute.resolved	Dispute resolved by admin

Webhook Payload

Example: dispute.opened

{
  "event": "dispute.opened",
  "data": {
    "dispute_id": "dis_abc123",
    "invoice_id": "inv_abc123",
    "amount": 99.99,
    "reason": "product_not_received",
    "opened_by": "buyer",
    "response_deadline": "2024-01-18T11:00:00Z"
  },
  "timestamp": "2024-01-15T11:00:00Z"
}

Example: dispute.resolved

{
  "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,
      "tx_hash": "blockchain_tx_hash"
    }
  },
  "timestamp": "2024-01-25T11:00:00Z"
}

---

Best Practices

For Merchants

✅ Respond Quickly - You have 3 days to respond to disputes ✅ Provide Clear Evidence - Shipping confirmations, delivery proofs, communication logs ✅ Keep Records - Store all transaction-related documentation ✅ Set Appropriate Buffer Periods - Longer buffers for physical goods ✅ Send Tracking Information - Update customers on delivery status ✅ Clear Product Descriptions - Accurate listings reduce disputes ✅ Responsive Support - Quick responses prevent escalation

Buffer Period Recommendations:

Product Type	Recommended Buffer
Digital Products	24-48 hours
US Shipping	7-10 days
International	14-21 days
Custom/Made-to-Order	21-30 days

For Buyers

✅ Act Quickly - Disputes must be opened before the buffer period expires ✅ Provide Detailed Description - Explain exactly what happened (minimum 20 characters) ✅ Include Evidence - Screenshots, emails, order confirmations ✅ Check Your Email - You'll receive updates at each stage ✅ Save Transaction Details - Keep invoice IDs and transaction hashes ✅ Contact Merchant First - Many issues can be resolved directly

---

Preventing Disputes

For Merchants

Strategy	Impact
Longer Buffer Periods	Gives time for delivery confirmation
Proactive Communication	Keeps buyers informed of order status
Clear Refund Policy	Sets expectations upfront
Quality Control	Reduces "not as described" claims
Fast Shipping	Reduces delivery-related disputes
Responsive Support	Resolves issues before escalation

---

FAQ

Q: How do buyers open disputes without a wallet? A: Buyers use email verification. They enter the email associated with the invoice, receive a 6-digit code, and use that code to open the dispute. No wallet connection required.

Q: What if I paid from Coinbase/Binance? A: Perfect! The email verification system is designed specifically for CEX users who can't sign with their wallets.

Q: How long do I have to open a dispute? A: You must open a dispute while funds are still in escrow (before the buffer period ends). Check the dispute_deadline in your invoice details.

Q: What happens if the merchant doesn't respond? A: If a merchant doesn't respond within 3 days, the dispute moves to admin review. Lack of response may weigh in favor of the buyer.

Q: Can I upload multiple files? A: Currently, you can upload one file when opening the dispute.

Q: How long does resolution take? A: Admin review typically takes up to 14 days from when all evidence is submitted. You'll receive email updates throughout the process.

Q: What if I lost the verification code? A: You can request a new code, but you're rate-limited to 3 requests per hour to prevent spam.

Q: Can I dispute a subscription charge? A: Yes. Subscription charges also go through escrow and can be disputed during the buffer period.

Q: What makes a strong dispute case? A: Detailed description, supporting evidence (screenshots, emails), clear timeline of events, and attempts to contact the merchant first.

---

Error Codes

Code	Message	Solution
400	Invalid code format	Code must be 6 digits
401	Email doesn't match invoice	Use the email from the invoice
401	Code expired	Request a new code (expires in 10 minutes)
404	Invoice not found	Check the invoice ID
409	Dispute already exists	Only one dispute per invoice
409	Buffer period expired	Disputes can't be opened after funds release
429	Rate limit exceeded	Wait before requesting another code
500	Blockchain transaction failed	Try again or contact support

---

Support

Need help with a dispute?

📧 Email: [email protected] 📚 Docs: https://docs.stablix.xyz/disputes