Disputes

Overview

A dispute (also called a chargeback) occurs when a shopper contests a charge with their card issuer. When that happens for a Violet order, Violet tracks the dispute against the affected PaymentTransaction and Bag, moves funds automatically as the dispute progresses, and notifies your channel through webhooks.

Disputes are handled for Stripe-backed payments. You don't take any action through the Violet API to process a dispute — evidence is submitted through the payment provider (see What you need to do) and Violet performs the resulting money movement on your behalf. This guide explains the states an order moves through and what each one means for funds.

---

How disputes fit the order & payment lifecycle

A dispute introduces a dispute_status that is orthogonal to capture state. From the API:

Dispute status of this payment transaction. Orthogonal to capture_status — a transaction can be CAPTURED and IN_DISPUTE simultaneously.

In other words, a payment that was successfully captured can later enter a dispute without changing its capture status. dispute_status is exposed on both the PaymentTransaction and the Bag (Bag.dispute_status), so you can read it wherever you already track payment or bag state.

A dispute does not roll back the order or the capture. The order remains captured and complete; the dispute is tracked alongside it and resolved independently.

For background on the surrounding lifecycle, see Order and Bag States and Payment Transactions.

---

Dispute states

dispute_status (on both PaymentTransaction and Bag) takes one of four values:

Status	Meaning
UNDISPUTED	No payment dispute has been filed for this Bag.
IN_DISPUTE	A payment dispute (chargeback) has been filed for this Bag and is under review.
DISPUTE_WON	The payment dispute was resolved in the merchant's favor.
DISPUTE_LOST	The payment dispute was resolved in the customer's favor.

---

What happens to funds

When a dispute is filed, the disputed funds are withdrawn by the card network while the case is reviewed. Violet keeps your payout position consistent with that automatically:

• Dispute opened — dispute_status becomes IN_DISPUTE, and Violet reverses the transfer that sent the disputed funds to the merchant so the clawback isn't stranded. See Transfer Reversals.

• Dispute won — dispute_status becomes DISPUTE_WON, and Violet issues a new transfer returning the funds to the merchant. (The original reversal is permanent; a fresh transfer restores the position.)

• Dispute lost (or resolved as charge_refunded) — dispute_status becomes DISPUTE_LOST. The chargeback stands, so the shopper keeps the funds and no new transfer is made. The affected bag's financial_status is set to DISPUTED_REFUNDED.

DISPUTED_REFUNDED vs REFUNDED

DISPUTED_REFUNDED indicates the shopper was made whole via a chargeback rather than via a Violet refund. It is distinct from REFUNDED so that dispute-recouped orders can be told apart from orders you refunded voluntarily — and so a lost dispute does not create a spurious refund record.

---

Webhook events

Violet emits standard webhooks at each stage so you can keep your own records in sync:

• PAYMENT_TRANSACTION_DISPUTE_OPENED — a dispute was opened against a payment transaction.

• PAYMENT_TRANSACTION_DISPUTE_WON — a dispute closed in the merchant's favor.

• PAYMENT_TRANSACTION_DISPUTE_LOST — a dispute closed in the shopper's favor.

• ORDER_DISPUTED — emitted once per order, on the first dispute opened against any of its payment transactions.

See Dispute Webhooks for the triggers, payload contents, and headers for each event.

---

Dispute fees

Card networks charge a dispute fee when a chargeback is filed, regardless of the outcome. In the current version this fee is absorbed by the platform; the fee amount is included on the dispute webhook payload for your visibility.

---

What you need to do

Disputes are informational from the Violet API's perspective — there is no dispute action to call:

• Submit evidence through Stripe. Contesting a dispute (uploading evidence) is done in the Stripe dashboard for the account that processed the payment. Violet does not proxy evidence submission in the current version.

• Let Violet move the funds. The payout reversal on open, and the re-payout on a win, happen automatically. You don't need to issue a refund or a transfer yourself.

• Reconcile from webhooks and status. Use the dispute webhooks and dispute_status / financial_status to update your own dashboards and reporting. A DISPUTE_LOST order shows financial_status = DISPUTED_REFUNDED rather than REFUNDED.

There is no per-app or per-merchant dispute configuration in the current version; behavior is the same for all channels.

---

Out of scope (current version)

The following are not part of the current dispute support and may be added later without breaking changes:

• Submitting dispute evidence through the Violet API (handled via Stripe today).

• Disputes for non-Stripe payment providers.

• Interim/inquiry notifications (e.g. early-warning or "updated" dispute states) — only opened and closed transitions are surfaced today.

---

Related Documentation

• Dispute Webhooks — events emitted across the dispute lifecycle

• Order and Bag States — surrounding order/bag lifecycle

• Payment Transactions — the payment model dispute_status lives on

• Transfers and Transfer Reversals — how funds move to and from merchants