Disputes represent a buyer, or their bank, challenging a payment: chargebacks, pre-dispute inquiries, and compliance cases. Each dispute links back to the payment intent and order it contests, carries the disputed amount_money, and records a reason (such as fraudulent, product_not_received, or duplicate) and a case_type (inquiry, chargeback, compliance, or resolution).
A dispute moves through statuses from needs_response and under_review to a terminal won, lost, or prevented, with warning_ variants for early inquiries that may still become formal chargebacks. The action_required, evidence_response_allowed, and evidence_due_at fields tell you whether and by when you can respond. evidence_deadline_passed is true once the due date is in the past; evidence_submission_past_due is reported by the card network when the deadline passed without an evidence submission. This surface is read-only over the API: list and retrieve disputes to monitor and reconcile them.
Subscribe to the dispute.created, dispute.updated, and dispute.closed webhook events so your systems react the moment a case opens or resolves, rather than polling.
When the disputed payment funded gift cards, Flint freezes spending on the original cards and any replacement cards carrying that funding. Each load's funding_disputes records the dispute identity and outcome. A win clears only that dispute's restriction. Other disputes and merchant freezes remain in effect.
A lost funding dispute preserves balances and unresolved reservations. That dispute's entry in each affected load's funding_disputes has requires_resolution: true. To honor the gift card value despite the lost funding, call POST /v1/gift-card-funding-dispositions with dispute_id, disposition: honor_value, reason_message, and a durable Idempotency-Key. This requires commerce.gift_cards.adjustments.write. The 201 response returns a GiftCardFundingDisposition that records the full disputed amount, original gift card consideration, honored face value, and preserved reservations. The disputed amount can include other purchases; these amounts must not be added together. The disposition clears only this dispute's restriction and sets resolution.disposition to honor_value on that dispute's funding_disputes entries. Retry with the same key to recover the committed result.