Respond with Evidence
To contest a chargeback you build a counter — your evidence response for one dispute phase. You compose it as a draft (continuously autosaved), then submit it to the processor in a single, final action.
Submission is one-shot and irreversible. Card disputes allow exactly one evidence response per phase — there is no within-phase back-and-forth with the issuer. Once you submit, the counter is locked and goes straight to the processor. Get the draft right before you submit it.
The counter lifecycle
A counter moves through these states:
A dispute usually has exactly one counter. A new counter is created only when a new phase/round opens: the dispute
re-enters needs_response at a higher phase, a fresh draft is created, and the previous submitted counter becomes
superseded. In practice, multi-phase rounds are rare.
Evidence categories
Evidence is a list of evidence_items, each tagging a canonical category with free text and/or attached
file_ids. Truemed maps these categories to the processor for you, so you provide evidence in one canonical form.
Categories:
product_description, customer_communication, customer_name, customer_email, customer_purchase_ip,
customer_signature, billing_address, receipt, shipping_documentation, shipping_tracking_number,
service_documentation, service_date, access_activity_log, refund_policy, refund_policy_disclosure,
refund_refusal_explanation, cancellation_policy, cancellation_policy_disclosure, cancellation_rebuttal,
duplicate_charge_documentation, duplicate_charge_explanation, uncategorized.
The dispute’s evidence_requirements (from the detail endpoint or the dispute.*
webhook) resolves the recommended evidence for the dispute’s reason, already grouped by weight: lead with the
compelling categories, then add supporting; other lists the remaining categories the processor accepts. Each entry
tells you whether it takes free text and/or a file, and merchant_explanation is Truemed’s narrative on how to
contest this reason. For example, a product_not_received dispute surfaces shipping_tracking_number and
service_documentation as compelling, while product_unacceptable surfaces product_description and your
refund_policy_disclosure. Provide the categories that best rebut the specific reason.
1. Create a draft
POST /api/v1/disputes/{dispute_id}/counters creates the draft. You may seed it with initial evidence or start empty.
The response is the counter, including its counter_id and revision (starts at the first revision). Persist both.
2. Autosave the draft
POST /api/v1/disputes/{dispute_id}/counters/{counter_id} upserts the draft. It’s a full replacement of
evidence_items and is built for autosave. There’s no fixed rate limit, but debounce saves to roughly one every
300–500 ms of idle typing rather than firing on every keystroke — enough to feel live without redundant writes.
Autosave validates the evidence shape (category capabilities, one file per category, no duplicate categories) and
rejects an invalid save with 422 — the persisted draft is left untouched. Empty or partially-filled items (a category
with no text or file yet) save fine, so an in-progress draft is never blocked; surface the 422 inline and keep the
merchant’s edits rather than discarding them.
To stay safe under concurrent editors, the draft is optimistically locked: send the revision you last read. If the
counter changed since (another editor saved first), the request is rejected with 409 Conflict — reload the counter and
retry with the new revision.
Evidence is saved server-side only — there is no client-side draft store — because dispute evidence can contain PHI.
3. Submit (one-shot)
POST /api/v1/disputes/{dispute_id}/counters/{counter_id}/submit submits your evidence to the processor. The counter
moves to submitted.
The dispute does not flip to under_review synchronously — that transition is driven by the resulting processor
webhook. Watch for dispute.updated and re-fetch the dispute for authoritative state.
Withdraw a draft
POST /api/v1/disputes/{dispute_id}/counters/{counter_id}/withdraw discards a draft you no longer want. Only drafts can
be withdrawn — a submitted counter is permanent.