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.