Skip to navigation
API ReferenceDisputes

Get Dispute

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:

StateMeaning
inquiryA pre-dispute warning or retrieval request. Not yet a chargeback; no funds withdrawn.
needs_responseAn open chargeback awaiting your evidence by due_by. The only state you can accept.
under_reviewEvidence submitted; the processor or card network is deciding.
wonResolved in your favor; funds retained.
lostResolved against you; funds withdrawn.
acceptedYou conceded the dispute (see Accept Dispute).
expiredThe evidence deadline passed with no response.
closedAn 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.

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Path parameters

business_idstringRequired

The Truemed dispute ID (UUID).

Response

Successful response
amountinteger
The original disputed amount in cents, independent of resolution.
created_atdatetime
When the dispute was created.
currencystring
ISO currency code of the disputed amount.
dispute_idstring

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

paymentobject
Summary of the payment the dispute was filed against.
processorenum
Payment processor the dispute originated from.
Allowed values:
processor_dispute_idstring

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

reasonenum
Canonical reason the dispute was filed.
stateenum
Canonical dispute state.
counterslist of objectsOptionalDefaults to []

Evidence counters for this dispute (the full chain across phases).

due_bydatetime or nullOptional
Evidence submission deadline, if the dispute is challengeable.
evidence_requirementsobjectOptional

Recommended evidence for this dispute’s reason, grouped by weight (compelling / supporting / other), plus Truemed’s merchant narrative on how to contest.

metadatamap from strings to anyOptionalDefaults to {}

Arbitrary merchant-set metadata.

network_reason_codestring or nullOptional

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

outcomeenum or nullOptional

Terminal outcome; null until the dispute resolves.

Allowed values:
payment_session_idstring or nullOptional

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

phaseenum or nullOptional

Which round of the dispute (inquiry, dispute, pre-arbitration, arbitration).

Allowed values:
prior_dispute_idstring or nullOptional

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

resolved_atdatetime or nullOptional
When the dispute reached a terminal state.

Errors

400
Bad Request Error
404
Not Found Error
405
Method Not Allowed Error
500
Internal Server Error
501
Not Implemented Error