# Dispute

object type

A Dispute — the Stripe chargeback lifecycle mirrored (SPEC_CATALOG 147; the / fraud-signal seed). NEVER wire-created: WEBHOOK-BORN from charge.dispute.created — the ingress resolves the parent Payment through the PI-metadata law, mints record-first (needs_response, deduped by a UNIQ reservation on disputeRef), appends Order.disputeIds (32 bound), and emits the payment_dispute_opened operational line (money-loss events are operator-mandatory). The processor holds the disputed funds while evidenceDueBy runs; won/lost land via charge.dispute.closed (an UNANSWERED dispute closing lost rides the two-edge cascade needs_response→under_review→lost — the must-pass-under_review law); on lost the funds+fee reverse REPORTS-ONLY. The TWO caller lanes carry authority:manage_dispute: submitEvidenceDispute (the evidence bespoke) and acceptDispute (concede via the processor close).

## Fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
| `sysId` | [String](/types/#scalars) `String!` | The group-scoped human-facing system id (DP-…). |
| `type` | [String](/types/#scalars) `String!` | The kind of record — always `Dispute` here. |
| `caption` | [String](/types/#scalars) `String!` | The record’s display name — what people see it called. |
| `status` | [String](/types/#scalars) `String!` | The FSM state: needs_response \| under_review \| won \| lost \| accepted. |
| `parentId` | [ID](/types/#scalars) `ID!` | The Payment whose charge is disputed; the record also names the Order anchoring the money story (orderId); rootId = the org group; parentId!== rootId always. |
| `rootId` | [ID](/types/#scalars) `ID!` | The org-group family root. |
| `createdAt` | [String](/types/#scalars) `String!` | When the record was created, as a UTC timestamp. |
| `updatedAt` | [String](/types/#scalars) `String!` | When the record last changed, as a UTC timestamp. |
| `revisionNum` | [Int](/types/#scalars) `Int!` | How many times this record has been edited; the first save is 0. |
| `revision` | [ID](/types/#scalars) `ID!` | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
| `refCaptions` | [RefCaption](/types/RefCaption/) `[RefCaption!]!` | The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption. |
| `organizationId` | [ID](/types/#scalars) `ID!` | The selling Organization (copied from the parent Payment at mint — attribution). |
| `orderId` | [ID](/types/#scalars) `ID!` | The Order anchoring the money story (the parent Payment’s own parent — the Order.disputeIds bounded-append twin). |
| `disputeRef` | [ID](/types/#scalars) `ID!` | The processor dispute ref (dp_…) — REQUIRED ALWAYS (webhook-born records carry their processor identity from birth; the UNIQ mint-dedup key). |
| `amountMinor` | [Int](/types/#scalars) `Int!` | The disputed amount in minor units (the processor’s figure VERBATIM — may differ from the payment on partial disputes). |
| `currency` | [String](/types/#scalars) `String!` | The dispute currency — the processor’s figure VERBATIM. |
| `reason` | [String](/types/#scalars) `String!` | The processor dispute reason code VERBATIM (e.g. fraudulent, product_not_received — the fraud-signal seed). |
| `evidenceDueBy` | [String](/types/#scalars) | The processor’s evidence deadline (UTC ISO-8601) — operator-facing urgency; the PROCESSOR enforces it (never scheduled against, SCH-1 class). |
| `stripeAccountRef` | [String](/types/#scalars) | The Connect account context THREADED from the parent Payment’s stamp. Null = the platform account. |
| `evidenceText` | [String](/types/#scalars) | The evidence text submitted through the caller lane (stamped WITH the respond flip — the presence law; null on dashboard-side submissions and the accept path). |

## Used by

- [acceptDispute](/reference/dispute/acceptDispute/)
- [dispute](/reference/dispute/dispute/)
- [submitEvidenceDispute](/reference/refunds-and-payment-corrections/submitEvidenceDispute/)