When a customer disputes a charge, Stripe creates a Dispute object and the disputed amount plus a dispute fee is deducted from your balance; retrieve the dispute via GET /v1/disputes/{id} and check status and reason
If you accept the dispute (POST /v1/disputes/{id}/close), Stripe closes the dispute in favor of the customer, the deducted amount and dispute fee remain gone, and no further action is needed — this is appropriate when the dispute is valid or evidence is insufficient
Do not issue a separate refund after accepting a dispute — the customer has already received their money back via the dispute; issuing a refund would double-pay the customer and the funds cannot be easily recovered
If you have issued a refund before the dispute was filed and the customer still disputed the charge, submit evidence showing the refund was issued (refund_id, refund date, and communication with the customer) via POST /v1/disputes/{id} with evidence.refund_policy_disclosure and evidence.refund_refusal_explanation
Submit dispute evidence before the deadline shown in evidence_details.due_by; missed deadlines result in automatic loss with no opportunity to contest
Monitor dispute lifecycle via charge.dispute.created, charge.dispute.updated, and charge.dispute.closed webhooks; build an internal tracking system that flags disputes and ensures evidence submission SLAs are met
Known gotchas
Issuing a refund on a charge that is already under active dispute does not automatically close the dispute — the refund and dispute are independent processes; you must also accept the dispute or submit evidence; otherwise both the refund and the dispute deduction may remain
Dispute fees are charged even if you win the dispute on some card networks — check current Stripe dispute fee policies per card brand as fee structures differ and Stripe's policies can change
Certain dispute reasons (e.g., credit_not_processed, duplicate) are better countered with specific evidence types — consult Stripe's dispute evidence guide per reason code rather than submitting generic evidence for all dispute types
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp