Dispute Management

Source: internal/api/v1/store/Controllers/dispute.js

Overview

The Dispute controller manages Stripe dispute (chargeback) operations including listing, retrieval, evidence submission, and dispute closure. It provides connected account sellers with tools to respond to customer disputes.

Key Capabilities

• List disputes with filtering and pagination
• Retrieve individual dispute details
• Update dispute evidence
• Submit evidence to Stripe
• Close disputes
• Upload evidence files

---

MongoDB Collections

Collection	Operations	Purpose
_store.disputes	Read, Update	Dispute tracking
_accounts	Read	Account/business info population

---

Service Methods

getDisputes

Lists all disputes for the connected account.

Endpoint: GET /store/disputes

Authorization: Requires payments_enabled = true

Query Parameters:

{
  page: number,
  limit: number,
  filter: object  // Optional: additional MongoDB filters
}

Response: Paginated dispute list with account/business info

Filtering:

{
  account: req.auth.account_id,
  connected_account: req.auth.account.stripe_connected_account
}

---

getDispute

Retrieves a single dispute by MongoDB _id.

Endpoint: GET /store/disputes/:id

Authorization: Requires payments_enabled = true

Response: Dispute object with populated account

---

updateDispute

Updates dispute evidence and optionally submits to Stripe.

Endpoint: PATCH /store/disputes/:id

Authorization: Requires payments_enabled = true

Request Body:

{
  evidence: {
    // Stripe evidence fields
    customer_name: string,
    customer_email_address: string,
    billing_address: string,
    receipt: string,               // File ID from uploadEvidence
    customer_signature: string,    // File ID
    shipping_documentation: string, // File ID
    // ... other Stripe evidence fields
  },
  submit: boolean  // Optional: submit evidence to Stripe
}

Response: Updated dispute object

Business Logic:

1. Find dispute with account access validation
2. Update Stripe dispute with evidence
3. Update MongoDB document
4. Return updated dispute with populated account

---

closeDispute

Closes a dispute, accepting the dispute loss.

Endpoint: POST /store/disputes/:id/close

Authorization: Requires payments_enabled = true

Response: Updated dispute object

Business Logic:

const dispute = await stripe.disputes.close(dispute.stripe_id, {
  stripeAccount: stripe_connected_account,
});

await StoreDispute.findByIdAndUpdate(id, { ...dispute });

---

uploadEvidence

Uploads evidence files to Stripe for use in dispute responses.

Endpoint: POST /store/disputes/:id/evidence/upload

Authorization: Requires payments_enabled = true

Request: Multipart form data with file

Response: Stripe file object with ID

Business Logic:

const file = await stripe.files.create(
  {
    purpose: 'dispute_evidence',
    file: {
      data: req.file.buffer,
      name: req.file.originalname,
      type: 'application.octet-stream',
    },
    file_link_data: {
      create: true,
    },
  },
  { stripeAccount: stripe_connected_account },
);

Usage: Returns file ID to be used in updateDispute evidence fields

---

Business Logic Flows

Dispute Evidence Submission

graph TD
    A[Get Dispute] --> B[Upload Evidence Files]
    B --> C[Get File IDs]
    C --> D[Update Dispute with Evidence]
    D --> E{Submit to Stripe?}
    E -->|Yes| F[Set submit: true]
    E -->|No| G[Save as Draft]
    F --> H[Stripe Reviews]
    G --> I[Can Edit Later]

Evidence Fields

Common Stripe evidence fields:

• customer_name: Customer's full name
• customer_email_address: Customer's email
• billing_address: Billing address
• receipt: Proof of purchase (file ID)
• customer_signature: Signed contract (file ID)
• shipping_documentation: Shipping proof (file ID)
• customer_communication: Communication logs (file ID)
• refund_policy: Refund policy document (file ID)
• cancellation_policy: Cancellation policy (file ID)
• product_description: Description of service/product

---

Edge Cases & Business Rules

1. Connected Account Only

All dispute operations require:

• payments_enabled = true
• Valid stripe_connected_account
• Account and connected_account must match authenticated account

2. Evidence Submission Timing

Evidence can be submitted multiple times until deadline:

• Draft updates: submit: false or omitted
• Final submission: submit: true
• Cannot modify after submission deadline

3. File Upload Requirements

• Purpose must be 'dispute_evidence'
• File buffer from multipart form
• Creates file link automatically for sharing

4. Dispute Status Tracking

Stripe dispute statuses:

• warning_needs_response: Evidence required
• warning_under_review: Evidence submitted, under review
• warning_closed: Closed, won
• lost: Dispute lost
• won: Dispute won

---

Related Documentation

• Webhooks - Dispute event synchronization
• Reporting - Dispute volume analytics
• Invoices - Related invoice information