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 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, 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 - The dispute lifecycle and what each state means for funds

• Payment Transactions - The payment model dispute_status lives on

• Transfer Reversals - How reversed funds are handled

• Handling Webhooks - Process dispute webhooks properly