# Setting Up Stripe Chargeback Prevention

> Connect your Stripe account to Fidro for automatic chargeback risk analysis and dispute handling.

**Category:** chargeback-prevention | **Last updated:** March 14, 2026

---

Fidro's chargeback prevention analyses every Stripe payment in real time, scoring it for fraud risk and optionally auto-refunding high-risk transactions before they become disputes. This feature is available on the **Pro plan**.

## How it works

1. A customer pays through Stripe
2. Stripe sends a `payment_intent.succeeded` webhook to Fidro
3. Fidro analyses the transaction (amount, card country, billing details, customer history)
4. The transaction appears in your [Transactions dashboard](/app/transactions) with a risk score
5. Based on your settings, Fidro can auto-refund, send you a notification, or both

## Step 1: Create a Stripe webhook

In your [Stripe Dashboard](https://dashboard.stripe.com/webhooks), create a new webhook endpoint:

**Endpoint URL:**
```
https://api.fidro.io/api/webhooks/stripe/YOUR_ACCOUNT_ID
```

Replace `YOUR_ACCOUNT_ID` with your Fidro account ID (found on your [Account settings](/app/settings/account) page).

**Events to listen for:**
- `payment_intent.succeeded` — triggers chargeback risk analysis
- `charge.dispute.created` — triggers dispute handling and optional auto-refund

## Step 2: Add the webhook signing secret

Copy the **Signing secret** from Stripe (starts with `whsec_`) and add it to your Fidro configuration. Contact support if you need help with this step.

## Step 3: Pass customer metadata

To get the most accurate risk scoring, include customer details in your Stripe payment metadata. Fidro reads these fields from the PaymentIntent metadata:

```javascript
// When creating a PaymentIntent
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2999,
  currency: 'usd',
  metadata: {
    // Core fields (recommended)
    customer_email: 'customer@example.com',
    customer_ip: req.ip,
    // Enhanced fields (optional — unlock additional checks)
    customer_account_age_minutes: String(accountAgeMinutes),
    customer_order_count: String(user.orderCount),
    customer_phone: user.phone || '',
    device_fingerprint_id: req.body.deviceId,
    session_duration_seconds: String(req.body.sessionDuration),
  },
});
```

### Laravel (Cashier)

```php
$user->charge(2999, $paymentMethod, [
    'metadata' => [
        'customer_email' => $user->email,
        'customer_ip' => request()->ip(),
        'customer_account_age_minutes' => (string) $user->created_at->diffInMinutes(now()),
        'customer_order_count' => (string) $user->orders()->count(),
        'customer_phone' => $user->phone ?? '',
    ],
]);
```

### Next.js / Node

```typescript
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2999,
  currency: 'usd',
  customer: customerId,
  metadata: {
    customer_email: user.email,
    customer_ip: request.headers['x-forwarded-for'] || request.socket.remoteAddress,
    customer_account_age_minutes: String(
      Math.floor((Date.now() - new Date(user.createdAt).getTime()) / 60000)
    ),
    customer_order_count: String(user.orderCount),
  },
});
```

Without metadata, Fidro still analyses the transaction using card data, AVS/CVC results, Stripe Radar signals, billing details, and amount — but including email and IP significantly improves accuracy. See [Passing Customer Metadata](/docs/guides/passing-metadata-to-stripe) for the full list of fields.

## Step 4: Configure your settings

Go to [Account Settings](/app/settings/account) and scroll to **Chargeback Prevention**. Here you can configure:

- **Risk thresholds** — Set the score boundaries for "refund" and "review" recommendations
- **Auto-refund high-risk transactions** — Automatically refund payments that score above your refund threshold
- **Auto-refund on dispute** — Automatically refund when Stripe notifies you of a chargeback dispute
- **Notification emails** — Get emailed when a high-risk transaction or dispute is detected

## Step 5: Monitor your transactions

Visit the [Transactions page](/app/transactions) to see all analysed payments with their risk scores, recommendations, and dispute status. Click any transaction for a full breakdown of the risk checks.

## What Fidro analyses

For each payment, Fidro runs up to 23 checks including:

- **Stripe Radar integration** — Incorporates Stripe's own risk assessment
- **AVS/CVC verification** — Address and security code check results from the card network
- **Prepaid card detection** — Prepaid and virtual cards flagged (2–4x higher chargeback rates)
- **Card/billing/IP country matching** — Three-way geo comparison
- **Transaction amount** — Unusually high amounts relative to your average
- **Customer email** — Cross-referenced against disposable email lists and blocklists
- **Customer IP** — Checked for VPN, proxy, Tor, and hosting IPs
- **Repeat patterns** — Multiple charges from the same card or email in a short window
- **Account age** — Very new accounts making purchases (optional metadata)
- **Device fingerprinting** — Same device across multiple accounts (optional metadata)
- **Session timing** — Unusually fast checkouts suggesting automation (optional metadata)

## Testing

Use Stripe's test mode with Fidro's test API key to simulate transactions without processing real payments. The webhook flow works identically in test mode.