> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/webhooks/events/dispute-webhooks.md). # Disputes Dispute webhooks notify your application when a shopper files a chargeback against an order and as that dispute is resolved. These events let you keep your own records in sync as Violet tracks dispute state and moves funds on your behalf. ## Overview Dispute webhooks relate to the **dispute (chargeback) lifecycle**, enabling you to monitor when a payment is disputed and how it is ultimately resolved. Dispute state is tracked on the affected `PaymentTransaction` and `Bag` via `dispute_status`, which is orthogonal to capture status — a transaction can be captured and in dispute at the same time. Learn more in the [Handling Disputes](/prism/payments/disputes.md) guide. ## Available Events ### PAYMENT\_TRANSACTION\_DISPUTE\_OPENED **Trigger:** When a shopper files a dispute (chargeback) against a payment transaction and the dispute is opened. **Use Case:** Subscribe to this event to: * Flag the order as disputed in your dashboards * Notify internal risk/operations teams * Begin gathering evidence to contest the dispute (submitted via Stripe) * Track the evidence-submission deadline * Reconcile the reversed merchant payout **Significance:** The payment transaction's `dispute_status` becomes `IN_DISPUTE`. The disputed funds have been withdrawn while the case is reviewed, and Violet has reversed the corresponding merchant transfer. The payload identifies the disputed payment and includes the dispute reason, the dispute fee, the current status, and the evidence-submission due date. ### ORDER\_DISPUTED **Trigger:** When the **first** dispute is opened against any payment transaction on an order. Emitted once per order. **Use Case:** Subscribe to this event to: * Track disputes at the order level (rather than per payment transaction) * Trigger order-level review or hold workflows * Avoid duplicate handling when an order has multiple disputed payment transactions **Significance:** Indicates the order now has at least one dispute. Per-payment detail arrives via the `PAYMENT_TRANSACTION_DISPUTE_*` events; this event is a convenience signal for order-level tracking. ### PAYMENT\_TRANSACTION\_DISPUTE\_WON **Trigger:** When a dispute closes in the merchant's favor. **Use Case:** Monitor this event to: * Mark the dispute as resolved successfully in your records * Confirm the merchant payout has been restored * Update financial reporting and merchant-facing dashboards **Significance:** The payment transaction's `dispute_status` becomes `DISPUTE_WON`. The disputed funds are returned and Violet issues a new transfer restoring the merchant's payout position. ### PAYMENT\_TRANSACTION\_DISPUTE\_LOST **Trigger:** When a dispute closes in the shopper's favor (resolved as `lost` or `charge_refunded`). **Use Case:** Monitor this event to: * Mark the dispute as lost in your records * Reconcile the order as recouped via chargeback rather than via a refund * Update loss reporting **Significance:** The payment transaction's `dispute_status` becomes `DISPUTE_LOST`, and the affected bag's `financial_status` is set to `DISPUTED_REFUNDED` (distinct from `REFUNDED`, since the shopper was made whole through the chargeback rather than a Violet refund). The chargeback stands and no new transfer is made. ## Webhook Headers Dispute webhooks include the [default webhook headers](/prism/webhooks/managing-webhook-headers.md), plus: ### X-Violet-Order-Id Contains the Violet Order ID associated with the dispute. ### X-Violet-Entity-Id Contains the ID of the entity the event is about: the **Payment Transaction ID** for the `PAYMENT_TRANSACTION_DISPUTE_*` events, and the **Order ID** for `ORDER_DISPUTED`. ## Common Integration Patterns ### Dispute Opened Flow ``` PAYMENT_TRANSACTION_DISPUTE_OPENED → Flag order as disputed → Notify risk team → Gather evidence (via Stripe) ORDER_DISPUTED → Apply order-level review/hold ``` ### Dispute Won Flow ``` PAYMENT_TRANSACTION_DISPUTE_WON → Mark dispute resolved → Confirm merchant payout restored → Update reporting ``` ### Dispute Lost Flow ``` PAYMENT_TRANSACTION_DISPUTE_LOST → Mark dispute lost → Order financial_status = DISPUTED_REFUNDED → Update loss reporting ``` ## Coordinating with Other Events Dispute events relate to the payment and transfer lifecycle. A typical dispute that resolves against the merchant looks like: ``` PAYMENT_TRANSACTION_DISPUTE_OPENED → Funds disputed; merchant transfer reversed ORDER_DISPUTED → Order flagged (first dispute) PAYMENT_TRANSACTION_DISPUTE_LOST → Dispute lost; bag financial_status = DISPUTED_REFUNDED ``` When the merchant prevails: ``` PAYMENT_TRANSACTION_DISPUTE_OPENED → Funds disputed; merchant transfer reversed PAYMENT_TRANSACTION_DISPUTE_WON → New transfer restores the merchant payout ``` ## Best Practices 1. **Treat `DISPUTE_OPENED` as time-sensitive** — the dispute payload includes an evidence-submission due date. Surface it promptly so evidence can be submitted in Stripe before the deadline. 2. **Track disputes at both levels** — use `ORDER_DISPUTED` for order-level workflows and the `PAYMENT_TRANSACTION_DISPUTE_*` events for per-payment detail. 3. **Distinguish `DISPUTED_REFUNDED` from `REFUNDED`** — a lost dispute marks the order `DISPUTED_REFUNDED`, not `REFUNDED`. Don't treat it as a voluntary refund in reporting. 4. **Don't double-handle funds** — Violet reverses and (on a win) re-issues the merchant payout automatically. Use these events for reconciliation and notification, not to trigger your own transfers or refunds. 5. **Log all dispute events** — maintain a complete dispute history per order for reconciliation and compliance. ## Related Documentation * [Handling Disputes](/prism/payments/disputes.md) - The dispute lifecycle and what each state means for funds * [Payment Transactions](/prism/payments/payments-during-checkout/payment-transactions.md) - The payment model `dispute_status` lives on * [Transfer Reversals](/prism/payments/payments-during-checkout/transfer-reversals.md) - How reversed funds are handled * [Handling Webhooks](/prism/webhooks/handling-webhooks.md) - Process dispute webhooks properly --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.violet.io/prism/webhooks/events/dispute-webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.