/stripe-dispute

name: stripe-dispute
description: Evaluate whether a Stripe dispute is economical to contest, then gather evidence and submit only when approved. Use for Stripe disputes, chargebacks, counter-disputes, evidence packages, or Stripe dispute IDs.

Stripe Dispute Evaluation and Evidence

Evaluate the economics first. When contesting is justified and approved, build an evidence package and submit it to Stripe. Works for any SaaS using Stripe and a user database with login or usage logs.

When to Use This Skill

Use this skill when the user:

• Receives a Stripe chargeback notification and wants to fight it
• Provides a dispute ID (`du_*`) and asks to "counter" / "rebut" / "fight" it
• Asks how to gather evidence for a dispute marked `fraudulent`, `product_not_received`, `product_unacceptable`, or `subscription_canceled`
• Wants an activity-log PDF showing a customer used their product

Required Environment Variables

STRIPE_SECRET_KEY=sk_live_...      # Stripe restricted/secret key with disputes:write scope
DATABASE_URL=postgres://...        # READ-ONLY connection to your app's user database (optional but recommended)
TERMS_URL=https://yoursite.com/terms   # URL to your published cancellation/refund policy
EVIDENCE_DIR=~/disputes            # Where to save the per-customer evidence folders

**Database safety:** all queries are SELECT-only. Never let this skill issue UPDATE/DELETE/INSERT.

Inputs

The user provides any of:

• Stripe dispute ID (`du_xxxxx`) — preferred
• Customer email — skill will look up the dispute
• Charge ID (`ch_xxxxx` or `py_xxxxx`)

Decide whether to contest first

Accepting a dispute can be the correct outcome. Never submit evidence merely because a case exists.

1. Verify live Stripe pricing. Under current US standard pricing, Stripe charges a $15 dispute-received fee automatically and another $15 dispute-countered fee when evidence is submitted. The received fee is sunk. The countered fee is returned only on a win. Use current live pricing if these amounts change. 2. Query the merchant's live Stripe dispute history. For defended win rate, count only closed disputes with `evidence_details.submission_count > 0`. Separate initial purchases from renewals and narrow to the same reason when the sample permits. Report wins, losses, open cases, and sample size. State when no exact-match precedent exists. 3. Calculate break-even probability and expected value after the countered fee and evidence-building labor. Do not invent a probability from case strength alone. 4. Use a conservative 30% minimum win-probability threshold unless the user provides a different threshold. If comparable data cannot support that threshold, recommend leaving the dispute unanswered. This avoids the countered fee, although the disputed amount and received fee remain lost. 5. Obtain explicit user approval before building files, uploading evidence, or submitting. Submission is final and fee-bearing.

Steps

1. Pull the dispute from Stripe

curl -s -u "$STRIPE_SECRET_KEY:" \
  "https://api.stripe.com/v1/disputes/$DISPUTE_ID" | python3 -m json.tool

Extract: `amount`, `reason`, `charge`, `evidence_details.due_by`, `evidence_details.submission_count`, `status`.

If `submission_count > 0` the dispute has already been countered — STOP and warn the user.

2. Pull the surrounding context

# Charge → tells you the payment method, risk score, billing details, customer ID
curl -s -u "$STRIPE_SECRET_KEY:" "https://api.stripe.com/v1/charges/$CHARGE_ID"

# Customer → name, email, default payment source
curl -s -u "$STRIPE_SECRET_KEY:" "https://api.stripe.com/v1/customers/$CUSTOMER_ID"

# All invoices for the customer → look for previously-undisputed payments
curl -s -u "$STRIPE_SECRET_KEY:" \
  "https://api.stripe.com/v1/invoices?customer=$CUSTOMER_ID&limit=100"

# Subscription (if recurring)
curl -s -u "$STRIPE_SECRET_KEY:" "https://api.stripe.com/v1/subscriptions/$SUB_ID"

Prior undisputed payments on the same card are useful corroboration for `fraudulent` claims. Always count them, but do not treat them as proof by themselves.

3. Look up the customer in your app database

Adapt these queries to your schema. A useful evidence shape:

-- User profile and self-reported cancel reason
SELECT id, email, created_at, plan_tier, stripe_customer_id,
       cancel_reason, cancelled_at, delete_reason
FROM users WHERE email ILIKE :email;

-- Login activity (timestamps + country + device)
SELECT created_at, country_code, device
FROM user_activity WHERE user_id = :uid ORDER BY created_at;

-- Things the customer created/used in your product
SELECT name, type, created_at, updated_at
FROM projects WHERE user_id = :uid AND deleted = false ORDER BY created_at;

-- Checkout / payment-related actions (proves intent)
SELECT timestamp, endpoint, payload FROM action_logs
WHERE user_id = :uid
  AND endpoint ~* '(subscribe|checkout|stripe|upgrade|pay)'
ORDER BY timestamp DESC;

For `product_not_received` claims, check the user's self-reported `cancel_reason`. If they cancelled citing "Poor user experience" or anything admitting use, that field directly contradicts the claim. Quote it verbatim, but do not infer a win rate from one fact.

4. Download supporting documents

FOLDER="$EVIDENCE_DIR/$(echo $CUSTOMER_NAME | tr '[:upper:] ' '[:lower:]-')-$(date +%Y-%m)"
mkdir -p "$FOLDER"

# Invoice PDFs (URLs come from the Stripe invoice objects)
curl -sL "$INVOICE_PDF_URL" -o "$FOLDER/invoice.pdf"

5. Capture your terms / cancellation policy as a PDF

Using Playwright (Node):

node -e "
const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
  await page.goto(process.env.TERMS_URL, { waitUntil: 'networkidle' });
  await page.pdf({ path: process.argv[1], format: 'A4', printBack