> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Disputes & chargebacks

> What happens when a buyer disputes a charge.

<Info>
  For the automated side — winning disputes for you and keeping your account out of the
  processor's danger zone — see [Chargeback Shield](/merchants/payments/chargeback-shield). This
  page covers the underlying model: where disputes live, how evidence works, and how to block
  abusive buyers.
</Info>

Disputes are filed against the gateway that processed the payment — not against Shoppex. Stripe
disputes land in Stripe, PayPal disputes land in PayPal. Shoppex surfaces them in your
dashboard so you don't have to monitor three places.

## How you find out

When a gateway notifies us of a new dispute, the order moves to a disputed state and you get an
event on the `order:disputed` webhook plus a dashboard notification. The Orders page shows the
dispute alongside the original order.

## Responding

Each gateway has its own evidence flow. Stripe gives you a deadline (typically 7-14 days
depending on the card network). PayPal disputes go through their resolution center with a
similar window.

You respond inside that gateway's interface — Stripe Dashboard or PayPal Resolution Center.
Shoppex doesn't proxy evidence submission, because the gateway is the one judging the case.

What Shoppex contributes: the order detail page shows everything we captured at checkout —
buyer IP, country, device fingerprint, order timestamp, fulfillment proof (download log,
serial delivered, role granted). Copy what's relevant into your gateway's evidence form.

## Prevention

Most disputes for digital goods come from buyers who don't recognize the charge on their
statement. Two things help:

* Set a clear shop name in **Settings → Shop**. This is what flows into the gateway's
  descriptor field.
* Send fulfillment quickly. Buyers who haven't received what they paid for after a few hours
  are more likely to dispute than wait for support.

## Blacklisting bad buyers

If a specific buyer disputes after fulfillment (also called "friendly fraud"), add them to
**Security → Blocked** (`/security/blocked`) to block future purchases. Shoppex supports
blocking by:

* Email
* IP address or IP range
* Country
* Domain
* ASN or ISP
* City
* Crypto wallet address

Use the most specific entry that matches the abuse. Country-level blocks are blunt; ASN or
IP-range blocks are usually what you want for a recurring abuser.