Listen for the charge.dispute.created webhook event; extract the dispute id, reason, evidence_due_by timestamp, and the associated charge.
Gather evidence relevant to the dispute reason (e.g., customer communication, shipping confirmation, refund policy); map each piece to the appropriate Evidence object field such as customer_email_address, shipping_documentation, or uncategorized_file.
Submit evidence by calling the Update Dispute endpoint (POST /v1/disputes/{id}) with the evidence object populated and submit set to true before the evidence_due_by deadline.
Be aware that a dispute_fee (the original dispute-received fee) is charged when the dispute is created and is non-refundable regardless of outcome — even if you win, this fee is not returned as of the policy change on 2025-06-17.
If Stripe closes the dispute in your favor, a separate dispute-countered fee that was charged when you submitted evidence will be refunded; the original dispute-received fee is not.
Reconcile dispute fees by querying the Balance Transactions API filtered by type dispute and type dispute_reversal to distinguish which fees were reversed.
Known gotchas
Since 2025-06-17, the original dispute-received fee is non-refundable even on a won dispute — only the separate dispute-countered fee (charged when evidence is submitted) is refunded on a win.
Setting submit to true is irreversible; once submitted, evidence cannot be changed, so validate all fields before submission.
Stripe does not retry evidence submissions; if evidence_due_by passes without submission, the dispute is automatically closed in the cardholder's favor.
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?