> 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/payments/disputes.md).

# 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](#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.

{% hint style="info" %}
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.
{% endhint %}

For background on the surrounding lifecycle, see [Order and Bag States](/prism/checkout-guides/guides/order-and-bag-states.md) and [Payment Transactions](/prism/payments/payments-during-checkout/payment-transactions.md).

***

## **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.                       |

```mermaid
stateDiagram-v2
    [*] --> UNDISPUTED
    UNDISPUTED --> IN_DISPUTE: chargeback filed
    IN_DISPUTE --> DISPUTE_WON: resolved for merchant
    IN_DISPUTE --> DISPUTE_LOST: resolved for shopper
    DISPUTE_WON --> [*]
    DISPUTE_LOST --> [*]
```

***

## **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](/prism/payments/payments-during-checkout/transfer-reversals.md).
* **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.

```mermaid
sequenceDiagram
    participant Shopper
    participant Network as Card Network / Issuer
    participant Violet
    participant Channel
    Shopper->>Network: Files chargeback
    Network->>Violet: Dispute opened
    Violet->>Violet: dispute_status = IN_DISPUTE<br/>merchant payout reversed
    Violet-->>Channel: PAYMENT_TRANSACTION_DISPUTE_OPENED
    Violet-->>Channel: ORDER_DISPUTED (first dispute on the order)
    Note over Network: Dispute reviewed (evidence submitted via Stripe)
    alt Resolved for merchant
        Network->>Violet: Dispute won
        Violet->>Violet: dispute_status = DISPUTE_WON<br/>new payout issued to merchant
        Violet-->>Channel: PAYMENT_TRANSACTION_DISPUTE_WON
    else Resolved for shopper
        Network->>Violet: Dispute lost / charge_refunded
        Violet->>Violet: dispute_status = DISPUTE_LOST<br/>bag financial_status = DISPUTED_REFUNDED
        Violet-->>Channel: PAYMENT_TRANSACTION_DISPUTE_LOST
    end
```

***

## **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](/prism/webhooks/events/dispute-webhooks.md) 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](/prism/webhooks/events/dispute-webhooks.md) — events emitted across the dispute lifecycle
* [Order and Bag States](/prism/checkout-guides/guides/order-and-bag-states.md) — surrounding order/bag lifecycle
* [Payment Transactions](/prism/payments/payments-during-checkout/payment-transactions.md) — the payment model `dispute_status` lives on
* [Transfers](/prism/payments/payments-during-checkout/transfers.md) and [Transfer Reversals](/prism/payments/payments-during-checkout/transfer-reversals.md) — how funds move to and from merchants


---

# 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/payments/disputes.md?ask=<question>&goal=<endgoal>
```

`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.