Disputes OverviewTechnical Preview
This chapter includes information about features or aspects of the platform that are still in Technical Preview.
Features still in Technical Preview may lack significant production stability and are subject to API changes without notice, including breaking API schema changes.
Please do not use a feature in Technical Preview in production without first consulting a support engineer.
Certain Technical Preview features may not be accessible to all Stitch users by default. These features can be enabled on a per client basis on request.
When a cardholder disputes one of your card transactions, the issuing bank raises a chargeback against you. Stitch notifies you that the dispute exists, tells you when a response is due, and gives you an API to respond with supporting evidence.
This section covers the headless integration: your systems receive the dispute and respond programmatically, with no dashboard involvement.
The two surfaces
| Surface | Direction | Purpose |
|---|---|---|
| Dispute webhooks | Stitch to you | Tells you a dispute was raised, that your evidence was recorded, and how the case was ultimately decided |
| Evidence submission API | You to Stitch | Uploads your supporting documents and submits them against the case |
The two are designed to be used together. dispute.created tells you a case needs a response and by when; the evidence API is how you respond; dispute.evidence_received confirms Stitch has durably recorded your submission.
Lifecycle
Every case begins with dispute.created and ends with exactly one terminal event: dispute.won, dispute.lost, dispute.auto_accepted, or dispute.partially_accepted.
Before you start
Stitch provisions the following before you integrate:
| Item | Used for | Notes |
|---|---|---|
| Webhook subscription | Receiving dispute events | Configured on Svix against the dispute event types you want. See Using Webhooks. |
| OAuth client | Submitting evidence | client_credentials grant with the client_file_management and client_evidence_submission scopes. See Client tokens. |
Subscribe to every dispute event type you intend to handle. Terminal events are the only signal that a case is closed, so a subscription that covers dispute.created alone will leave cases open in your system indefinitely.
Concepts worth knowing up front
disputeId identifies the dispute. The dsp_-prefixed value is present on every webhook and matches the id returned by the Disputes API. Use it as the durable primary key in your own schema.
caseReference identifies the bank case. A human-readable reference such as STDB100, present on every webhook for that dispute and used as the path parameter when you submit evidence. Treat it as opaque and pass it back unmodified.
evidenceDueAt is the authoritative deadline. It is always present on dispute.created, and repeated on dispute.evidence_received so you can measure whether you responded in time. Do not hardcode a response window; read the field. Submitting after the deadline returns 410 DEADLINE_EXPIRED.
A case accepts one successful evidence submission. Uploads are incremental and reversible, but submission is a single atomic, final act. Plan to gather everything you need before you call the submit endpoint. See One submission per case.
Terminal events are mutually exclusive. You receive exactly one per resolved case, so you can treat any terminal event as the case's final state.
Next: receive dispute webhooks, then submit evidence.