Disputes

A dispute is the network's term for "the cardholder called their bank and questioned a charge." Frame surfaces it as a Dispute record on your platform, kicks off a structured response process, and gives you the surfaces to either submit evidence defending the charge or accept the reversal.

The distinction worth holding: a refund is something the merchant initiates voluntarily; a dispute is something the cardholder initiates through their issuing bank, and the resolution is mediated by the card networks (Visa, Mastercard, etc.) — not by Frame and not by the merchant directly. Frame is the conduit + evidence-submission interface; the network is the judge.

Lifecycle

The dispute status field moves through a sequence determined by the network. Frame's state machine has ~19 fine-grained states tracking each step of the evidence collection, submission, and review process; the merchant-facing milestones are:

Most platforms only need to react to Received (trigger evidence collection workflow) and Resolved-won / Resolved-lost (update bookkeeping). The intermediate states are surfaces for advanced operations dashboards.

Networks set strict deadlines (typically 7-21 days depending on card brand + reason category). Missing a deadline on awaiting_response is functionally identical to losing the dispute. Build deadline tracking into your operations.

What the cardholder claims

The reason object on a dispute carries the cardholder's stated rationale, populated by the issuing bank when the dispute is filed:

• reason.code — a machine-readable code (e.g., fraudulent, duplicate, product_not_received, subscription_canceled).
• reason.category — broader bucket (fraud, quality, processing_error, etc.).
• reason.description — human-readable description for dashboard display.

The reason determines what evidence is most effective at defense. A fraudulent dispute is best fought with proof of cardholder identity verification (3DS cryptogram, AVS match, IP geolocation). A product_not_received dispute needs shipping records + tracking + delivery confirmation. The dispute concept gets resolved on the evidence concept — the more your platform can attach, the higher the win rate.

Evidence submission

Disputes can have multiple evidence documents attached, each handled through POST/v1/disputes/{id}/documents. Typical evidence:

• Transaction records — original charge, AVS results, CVV match, 3D Secure cryptogram (if card verification ran).
• Customer identity — KYC verification records, signed agreements, login records showing the cardholder's account activity around the charge time.
• Fulfillment — shipping labels, delivery confirmation, screenshots of in-app activity, downloads of digital content.
• Communication — emails or chat logs showing the cardholder acknowledged the purchase or didn't dispute through your support channel first.
• Refund offer — if you offered a refund before the dispute and the cardholder declined, that's important context.

Each document attaches to the dispute via POST/v1/disputes/{id}/documents. Submit the complete evidence package before transitioning to under_review — once submitted, you typically can't add to it.

3DS cryptograms

If the original charge ran through 3D Secure, the cryptogram (cryptographic proof the issuer authenticated the cardholder) is stored on the related CardVerificationChallenge record. The cryptogram shifts liability for fraud-category disputes from the merchant to the issuer — that's why running card verification (link-time 3DS) or 3D Secure (charge-time 3DS) is the most important up-front investment for dispute defense.

Attaching the cryptogram to a specific dispute's evidence is a manual step in V1 — Frame stores the proof, but submitting it as evidence on a specific chargeback is part of your evidence-package preparation (alongside fulfillment records, customer identity, etc.). Frame's risk operations team can help correlate stored cryptograms to disputes; future versions may automate the linkage.

Outcome handling

When a dispute reaches won:

• Funds stay with the merchant (the original charge is not reversed).
• A network-applied chargeback fee may still apply, depending on your platform's processing relationship — Frame's billing surfaces this separately if so.
• The dispute record is retained for audit + future-trend analysis.

When a dispute reaches lost:

• Funds are returned to the cardholder.
• Frame creates a reversal entry on the original transfer's records (separate from refunds — see refunds for the voluntary-merchant case).
• Chargeback fees apply.
• The dispute record persists.

Disputes vs refunds — when to do which

If the cardholder reaches out before going to their bank, refund proactively. Refunds avoid chargeback fees, preserve the customer relationship, and don't count against your dispute-ratio compliance metrics (high dispute ratios trigger card-network warnings).

If the cardholder has already filed the dispute, respond through Frame's evidence flow. A late refund doesn't withdraw the dispute — once filed, the dispute runs its course; the cardholder's bank has its own protocols.

This decision tree matters for ratios: card networks (Visa, Mastercard) measure each merchant's dispute count vs total transactions. Crossing 1% triggers monitoring; crossing 1.8% can trigger termination. Preferring refunds over disputes when both are options is risk hygiene.

Webhooks

Subscribe to dispute events to react in real time:

• dispute.created — new dispute opened, typically received or warning_needs_response status.
• dispute.updated — status changed (response submitted, under review, resolved).
• dispute.closed — terminal state reached (won or lost).

The webhook payload includes the dispute record plus a reference to the original charge intent. Use it to surface in your dashboards, kick off your evidence-collection workflows, and update merchant-facing dispute counters.

Gotchas

Symptom: you submitted evidence and the dispute went to under_review, but the deadline passed and you got lost anyway. Why: "submitted" in Frame doesn't always mean "submitted to the network in time." Some categories require a multi-step submission — Frame stores evidence on its side, but the network-side deadline can be earlier than the platform-side deadline for inquiry stages. Fix: respond as early as possible, especially for warning_* statuses; treat the earliest network deadline as authoritative, not Frame's last-modified timestamp.

Symptom: a dispute is lost but the customer says they didn't initiate one. Why: "friendly fraud" is real — cardholders sometimes don't remember a charge and call their bank reflexively. Or a household member used the card without their knowledge. Fix: this happens; the dispute outcome stands. Track the cardholder's account on your platform — repeat friendly fraud is a signal worth your platform's risk team factoring into future-charge decisions.

Symptom: your dispute ratio is climbing despite few actual disputes. Why: the ratio is disputes / total_transactions — if your transaction volume drops (seasonal, churn, etc.) while disputes stay roughly constant, the ratio rises. Fix: dispute count, not ratio, is the operational lever. Reduce count via better up-front verification (KYC, 3DS, card verification) and proactive refunds.

Reference

For the full API surface, see GET/v1/disputes and the rest of the Disputes resource.