Working with the Stripe Disputes API

An engineer's reference for the Stripe Disputes API: webhook events, evidence fields, submission semantics, and the most common integration mistakes.

[Body content to be written.]

Audience

[Body content to be written. This is a technical reference for engineers integrating with the Stripe Disputes API directly — either to build their own representment automation or to understand what their dispute-defense vendor is actually doing.]

Webhook lifecycle

[Body content to be written. Walk through the dispute-related webhook events: charge.dispute.created, charge.dispute.updated, charge.dispute.closed, and charge.dispute.funds_withdrawn / charge.dispute.funds_reinstated.]

The evidence object

[Body content to be written. Tabular reference of the evidence fields Stripe accepts: customer_name, billing_address, receipt, customer_signature, shipping_documentation, shipping_date, shipping_carrier, shipping_tracking_number, etc. Note which fields take strings vs. file URIs.]

Submitting evidence

[Body content to be written. Cover the submit: true flag, partial submission semantics, and the deadline (evidence_details.due_by). Discuss why you should never let the deadline pass without submission — even a weak submission beats an automatic loss.]

Common pitfalls

[Body content to be written. Surface the issues we see repeatedly:]

[Body content to be written. Race condition: building the evidence package after the webhook arrives but before the merchant's logistics provider has indexed the shipment.]
[Body content to be written. File size limits and how to handle large PDFs.]
[Body content to be written. The ambiguity of uncategorized_text vs. structured fields.]
[Body content to be written. Stripe API version pinning.]

Useful debugging tips

[Body content to be written. Stripe's "View test data" toggle, the stripe-cli's ability to replay specific events, and how to inspect the raw evidence object via disputes.retrieve().]