disputes

Retrieve a single dispute, including its canonical state, deadlines, and evidence requirements

Retrieve a single dispute by its Truemed dispute_id, with everything you need to decide how to respond: its canonical state and phase, the reason code, the disputed amount and currency, the evidence deadline, and the recommended evidence for the dispute's reason. Only disputes on your own sales channel's payments are accessible — any other ID returns 404.

Response Notes

state is processor-agnostic. Every dispute, whatever the processor, maps to one of eight canonical states:

State	Meaning
inquiry	A pre-dispute warning or retrieval request. Not yet a chargeback; no funds withdrawn.
needs_response	An open chargeback awaiting your evidence by due_by. The only state you can accept.
under_review	Evidence submitted; the processor or card network is deciding.
won	Resolved in your favor; funds retained.
lost	Resolved against you; funds withdrawn.
accepted	You conceded the dispute (see Accept Dispute).
expired	The evidence deadline passed with no response.
closed	An inquiry that resolved without becoming a chargeback — a favorable no-contest outcome, tracked separately from won.

phase (inquiry, dispute, pre_arbitration, arbitration) is orthogonal to state: it tells you which round of the lifecycle you're in, not whether the dispute is open or resolved.
outcome is null until the dispute reaches a terminal state (won, lost, accepted, expired, closed).
amount is the original disputed amount in cents and does not change with the outcome; currency is the ISO code.
due_by is set only while the dispute is challengeable — it's null for inquiries and for resolved disputes.
evidence_requirements is the recommended evidence for this dispute's reason, resolved by Truemed: a merchant_explanation narrative (Markdown) plus categories grouped by weight into compelling, supporting, and other, each entry carrying its canonical category, display label, helper description, and whether it takes free text and/or a file.
counters is the full chain of evidence submissions (counters) for this dispute across phases.
State, amounts, and deadlines are read-only and advance only through processor events. The only writable fields are exposed through Accept Dispute and Update Dispute Metadata.

get/api/v1/disputes/{business_id}

Request

Base URL: https://dev-api.truemed.com
URL: https://dev-api.truemed.com/api/v1/disputes/{business_id}
Auth: API key in header x-truemed-api-key

Path parameters

business_idstring required

The Truemed dispute ID (UUID).

Response

Successful response

amountinteger required

The original disputed amount in cents, independent of resolution.

created_atstring date-time required

When the dispute was created.

currencystring required

ISO currency code of the disputed amount.

dispute_idstring required

Stable Truemed dispute ID (UUID). Use this as the dispute's identifier.

due_bystring date-time nullable

Evidence submission deadline, if the dispute is challengeable.

metadataobject

Arbitrary merchant-set metadata.

network_reason_codestring nullable

Raw card-network reason code behind the dispute (e.g. Visa 10.4), if provided.

outcome'won' | 'lost' | 'accepted' | 'expired' | 'closed'

Denormalized terminal outcome of a dispute; null until terminal.

payment_session_idstring nullable

The Truemed payment session this dispute belongs to. Null for disputes on non-payment-session charges.

phase'inquiry' | 'dispute' | 'pre_arbitration' | 'arbitration'

Which round of a dispute this is — orthogonal to DisputeState (comparison doc §4.3/§5).

prior_dispute_idstring nullable

Truemed dispute ID (UUID) of the prior round in a pre-arbitration/re-filing chain, if any.

processor'STRIPE' | 'FAKE' | 'EXTERNAL' required

Payment platforms supported by the public dispute API.

processor_dispute_idstring required

Raw payment-processor dispute ID (e.g. Stripe du_…), for reconciliation.

Canonical, card-network dispute reason — the only reasons Truemed can receive, since it settles HSA/FSA card payments over Stripe and never ACH/bank-debit. The enum is the processor-independent contract: each processor adapter maps its native reason vocabulary into this set (Adyen's raw card-scheme reason codes collapse into these buckets), so the enum itself carries no processor specifics.

Human labels live in _DISPUTE_REASON_LABELS, exposed via .label — the single backend contract the frontend and merchant emails hydrate from instead of maintaining their own label maps.

resolved_atstring date-time nullable

When the dispute reached a terminal state.

Canonical, processor-agnostic dispute state — the 8-state model in the Processor Disputes Comparison doc §4.3. Distinct from the Stripe-shaped DisputeStatus: a processor adapter maps raw status/eventCodes → (DisputeState, DisputePhase). closed is the favorable no-contest inquiry outcome (excluded from win-rate), kept separate from won.

Changes

No recorded changes to this operation across all 1 revision of this API.