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 `ID!`	The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it.
`sysId`	String `String!`	The group-scoped human-facing system id (DP-…).
`type`	String `String!`	The kind of record — always `Dispute` here.
`caption`	String `String!`	The record’s display name — what people see it called.
`status`	String `String!`	The FSM state: needs_response \| under_review \| won \| lost \| accepted.
`parentId`	ID `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 `ID!`	The org-group family root.
`createdAt`	String `String!`	When the record was created, as a UTC timestamp.
`updatedAt`	String `String!`	When the record last changed, as a UTC timestamp.
`revisionNum`	Int `Int!`	How many times this record has been edited; the first save is 0.
`revision`	ID `ID!`	The OCC revision token — supply it on every mutation of this record; rotates on every write.
`refCaptions`	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 `ID!`	The selling Organization (copied from the parent Payment at mint — attribution).
`orderId`	ID `ID!`	The Order anchoring the money story (the parent Payment’s own parent — the Order.disputeIds bounded-append twin).
`disputeRef`	ID `ID!`	The processor dispute ref (dp_…) — REQUIRED ALWAYS (webhook-born records carry their processor identity from birth; the UNIQ mint-dedup key).
`amountMinor`	Int `Int!`	The disputed amount in minor units (the processor’s figure VERBATIM — may differ from the payment on partial disputes).
`currency`	String `String!`	The dispute currency — the processor’s figure VERBATIM.
`reason`	String `String!`	The processor dispute reason code VERBATIM (e.g. fraudulent, product_not_received — the fraud-signal seed).
`evidenceDueBy`	String	The processor’s evidence deadline (UTC ISO-8601) — operator-facing urgency; the PROCESSOR enforces it (never scheduled against, SCH-1 class).
`stripeAccountRef`	String	The Connect account context THREADED from the parent Payment’s stamp. Null = the platform account.
`evidenceText`	String	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).

Dispute

Fields

Used by