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 and evidence_submission_past_due tell you when that window has closed. 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.