List disputes | MVS Developer Docs

{
  "disputes": [
    {
      "dispute_id": "dp_Qx12sample",
      "payment_id": "pay_Qp7sample123",
      "amount": 2500,
      "currency": "USD",
      "dispute_status": "dispute_opened",
      "connector_reason": "fraudulent",
      "extension": {
        "id": "dext_01",
        "organizationId": "org_acme",
        "hyperswitchDisputeId": "dp_Qx12sample",
        "source": "HYPERSWITCH",
        "disputeStatus": "NEEDS_RESPONSE",
        "alertPriority": "high",
        "platformNotes": "Customer claims non-receipt; tracking shows delivered.",
        "assignedToUserId": "user_42",
        "createdAt": "2026-06-20T18:04:11.000Z",
        "updatedAt": "2026-06-20T18:04:11.000Z"
      }
    },
    {
      "dispute_id": "nmi:cb_88421",
      "amount": 4999,
      "currency": "USD",
      "dispute_status": "NEEDS_RESPONSE",
      "connector_reason": "4853",
      "source": "NMI",
      "created_at": "2026-06-19T09:30:00.000Z",
      "extension": {
        "id": "dext_02",
        "organizationId": "org_acme",
        "hyperswitchDisputeId": "nmi:cb_88421",
        "source": "NMI",
        "nmiChargebackCaseId": "cb_88421",
        "reasonCode": "4853",
        "disputeAmount": 4999,
        "disputeCurrency": "USD",
        "disputeStatus": "NEEDS_RESPONSE"
      }
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Lists disputes for the authenticated organization. Each Hyperswitch dispute is joined with its org-scoped disputeExtension sidecar (alert priority, assigned user, platform notes, evidence status).

NMI-sourced chargebacks (ADR-014) have no Hyperswitch dispute object and never appear in the router’s dispute list, so they are pulled from the extension surface and presented inline with a synthetic dispute shape (source: "NMI"). The returned total is the router’s total_count (or the joined count) plus the count of NMI rows in this page.

Lists disputes for the authenticated organization. Each Hyperswitch dispute is joined with its org-scoped `disputeExtension` sidecar (alert priority, assigned user, platform notes, evidence status). NMI-sourced chargebacks (ADR-014) have no Hyperswitch dispute object and never appear in the router's dispute list, so they are pulled from the extension surface and presented inline with a synthetic dispute shape (`source: "NMI"`). The returned `total` is the router's `total_count` (or the joined count) plus the count of NMI rows in this page.

Authentication

x-api-keystring

A scoped MvsPayApiKey, e.g. mvspay_live_…. Mint and scope keys from the dashboard (Settings → API Keys).

Query parameters

limitintegerOptionalDefaults to 50

Max rows to return.

offsetintegerOptionalDefaults to 0

Rows to skip.

Response

A page of disputes, each with its extension sidecar (or null), plus inline NMI chargebacks.

disputeslist of objects

Hyperswitch disputes (with extension) followed by inline NMI chargebacks.

totalinteger

Router total_count (or joined count) plus the NMI rows in this page.

limitinteger

offsetinteger

Errors

401

Unauthorized Error

403

Forbidden Error

500

Internal Server Error

502

Bad Gateway Error

$	curl https://pay.mvscloud.com/api/disputes \
>	-H "x-api-key: <apiKey>"