stripe-dispute

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Stripe Dispute Fighter

Stripe争议应对工具

Build evidence packages and submit counter-disputes to Stripe. Works for any SaaS that uses Stripe + a user database with login/usage logs.
构建证据包并向Stripe提交反申诉。适用于所有使用Stripe + 包含登录/使用日志的用户数据库的SaaS产品。

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
当用户出现以下情况时使用:
  • 收到Stripe拒付通知并希望应对
  • 提供争议ID(
    du_*
    )并要求「申诉」「反驳」「应对」
  • 询问如何为标记为
    fraudulent
    (欺诈)、
    product_not_received
    (未收到商品)、
    product_unacceptable
    (商品不合格)或
    subscription_canceled
    (已取消订阅)的争议收集证据
  • 需要一份显示客户使用过产品的活动日志PDF

Required Environment Variables

所需环境变量

bash
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.
bash
STRIPE_SECRET_KEY=sk_live_...      # 具备disputes:write权限的Stripe受限/密钥
DATABASE_URL=postgres://...        # 应用用户数据库的只读连接(可选但推荐)
TERMS_URL=https://yoursite.com/terms   # 已发布的取消/退款政策URL
EVIDENCE_DIR=~/disputes            # 保存客户专属证据文件夹的路径
数据库安全提示: 所有查询仅为SELECT操作。绝不能让此工具执行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
    )
用户需提供以下任意一项:
  • Stripe争议ID(
    du_xxxxx
    )——首选
  • 客户邮箱——工具将查找对应争议
  • 收费ID(
    ch_xxxxx
    py_xxxxx

Steps

操作步骤

1. Pull the dispute from Stripe

1. 从Stripe拉取争议信息

bash
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.
bash
curl -s -u "$STRIPE_SECRET_KEY:" \
  "https://api.stripe.com/v1/disputes/$DISPUTE_ID" | python3 -m json.tool
提取字段:
amount
reason
charge
evidence_details.due_by
evidence_details.submission_count
status
submission_count > 0
,说明争议已提交过反申诉——立即停止并提醒用户。

2. Pull the surrounding context

2. 拉取相关上下文信息

bash
undefined
bash
undefined

Charge → tells you the payment method, risk score, billing details, customer ID

收费记录 → 包含支付方式、风险评分、账单详情、客户ID

curl -s -u "$STRIPE_SECRET_KEY:" "https://api.stripe.com/v1/charges/$CHARGE_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"
curl -s -u "$STRIPE_SECRET_KEY:" "https://api.stripe.com/v1/customers/$CUSTOMER_ID"

All invoices for the customer → look for previously-undisputed payments

客户所有发票 → 查找此前未争议的付款记录

Subscription (if recurring)

订阅信息(若为 recurring 订阅)

curl -s -u "$STRIPE_SECRET_KEY:" "https://api.stripe.com/v1/subscriptions/$SUB_ID"

**Prior undisputed payments on the same card are the strongest single piece of evidence** for `fraudulent` claims. Always count them.
curl -s -u "$STRIPE_SECRET_KEY:" "https://api.stripe.com/v1/subscriptions/$SUB_ID"

**针对`fraudulent`(欺诈)类争议,最强有力的证据是同一卡片此前无争议的付款记录**,务必统计此类记录数量。

3. Look up the customer in your app database

3. 在应用数据库中查询客户信息

Adapt these queries to your schema. The shape that wins disputes:
sql
-- 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;
Critical for
product_not_received
claims:
check the user's self-reported
cancel_reason
. If they cancelled citing "Poor user experience" or anything that admits they used the product, that single field contradicts the dispute claim and tends to win the case on its own. Quote it verbatim in the rebuttal.
根据你的数据库架构调整以下查询。能提升胜诉率的查询结构:
sql
-- 用户资料及自行填写的取消原因
SELECT id, email, created_at, plan_tier, stripe_customer_id,
       cancel_reason, cancelled_at, delete_reason
FROM users WHERE email ILIKE :email;

-- 登录活动(时间戳 + 国家 + 设备)
SELECT created_at, country_code, device
FROM user_activity WHERE user_id = :uid ORDER BY created_at;

-- 客户在产品中创建/使用的内容
SELECT name, type, created_at, updated_at
FROM projects WHERE user_id = :uid AND deleted = false ORDER BY created_at;

-- 结账/支付相关操作(证明购买意图)
SELECT timestamp, endpoint, payload FROM action_logs
WHERE user_id = :uid
  AND endpoint ~* '(subscribe|checkout|stripe|upgrade|pay)'
ORDER BY timestamp DESC;
针对
product_not_received
(未收到商品)类争议的关键:
查看用户自行填写的
cancel_reason
。若用户取消时填写「用户体验差」或任何承认使用过产品的理由,该字段可直接反驳争议主张,往往能直接胜诉。需在申诉原文中逐字引用。

4. Download supporting documents

4. 下载支持文档

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

Invoice PDFs (URLs come from the Stripe invoice objects)

发票PDF(URL来自Stripe发票对象)

curl -sL "$INVOICE_PDF_URL" -o "$FOLDER/invoice.pdf"
undefined
curl -sL "$INVOICE_PDF_URL" -o "$FOLDER/invoice.pdf"
undefined

5. Capture your terms / cancellation policy as a PDF

5. 将条款/取消政策捕获为PDF

Using Playwright (Node):
bash
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', printBackground: true });
  await browser.close();
})();
" "$FOLDER/cancellation_policy.pdf"
使用Playwright(Node):
bash
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', printBackground: true });
  await browser.close();
})();
" "$FOLDER/cancellation_policy.pdf"

6. Generate the activity-log PDF

6. 生成活动日志PDF

This is the document Stripe's reviewers actually read. Build an HTML file, then convert to PDF with WeasyPrint:
python
from weasyprint import HTML
HTML('activity_log.html').write_pdf('activity_log.pdf')
HTML must include
<meta charset="UTF-8">
to avoid mangled characters in customer names/addresses.
The layout that has been shown to win:
  1. Summary grid — Customer / Email / Internal user ID / Stripe customer ID / Account created / Plan / Subscription start / Cancellation timestamp (with delta from signup) / Self-reported cancel reason / Credits or units consumed / Purchase IP / Billing address / Payment method (last4, brand) / Stripe risk assessment / Referral source / Payment trigger
  2. Payment History table — every invoice with date, amount, status. Highlight the disputed row in red. Add a column "Disputed?" with explicit Yes/No.
  3. Checkout Attempts table — proves deliberate purchase intent (defeats
    fraudulent
    by extension)
  4. Items Created / Used table — names, types, timestamps. Concrete usage > adjectives.
  5. Login Activity Log — every session: timestamp, country, device. Consistency = same cardholder.
  6. Timeline Summary — single chronological narrative ending with "and then on $DATE the dispute was filed."
  7. Conclusion paragraph — quote the user's own
    cancel_reason
    against the stated dispute reason, if they contradict.
Concrete numbers beat adjectives every time. "29 login sessions, 3 named projects, 29,960 credits consumed, 1h 27m active, 2 deliberate checkout attempts" is undeniable. "Used extensively" is not.
这是Stripe审核人员实际会阅读的文档。先构建HTML文件,再用WeasyPrint转换为PDF:
python
from weasyprint import HTML
HTML('activity_log.html').write_pdf('activity_log.pdf')
HTML必须包含
<meta charset="UTF-8">
,避免客户姓名/地址出现乱码。
已验证能提升胜诉率的布局:
  1. 摘要表格 — 客户姓名/邮箱/内部用户ID/Stripe客户ID/账户创建时间/套餐/订阅开始时间/取消时间(距注册时长)/自行填写的取消原因/消费额度/购买IP/账单地址/支付方式(后四位、品牌)/Stripe风险评估/推荐来源/支付触发方式
  2. 支付历史表格 — 所有发票的日期、金额、状态。用红色高亮争议记录,添加「是否争议」列,明确标注是/否。
  3. 结账尝试表格 — 证明主动购买意图(间接反驳
    fraudulent
    欺诈主张)
  4. 创建/使用内容表格 — 名称、类型、时间戳。具体使用记录优于模糊描述。
  5. 登录活动日志 — 所有会话:时间戳、国家、设备。一致性=同一持卡人。
  6. 时间线摘要 — 按时间顺序的完整叙事,结尾为「随后于$DATE提交争议」。
  7. 结论段落 — 若用户的
    cancel_reason
    与争议理由矛盾,逐字引用进行反驳。
具体数据永远优于模糊形容词。「29次登录会话、3个命名项目、消耗29960额度、活跃1小时27分钟、2次主动结账尝试」无可辩驳,而「大量使用」则无效。

7. Show everything to the user before submitting

7. 提交前向用户展示所有内容

bash
open "$FOLDER"
Display the rebuttal text, the evidence files, and your win-probability assessment. Wait for explicit user approval.
bash
open "$FOLDER"
展示申诉文本、证据文件及胜诉概率评估。等待用户明确批准后再提交

8. Upload evidence files to Stripe

8. 将证据文件上传至Stripe

Files go to
files.stripe.com
, NOT
api.stripe.com
— different host:
bash
curl -s -u "$STRIPE_SECRET_KEY:" \
  -F "purpose=dispute_evidence" \
  -F "file=@$FOLDER/activity_log.pdf" \
  https://files.stripe.com/v1/files
Returns
{"id": "file_xxx", ...}
. Capture the
id
— that's what you reference in evidence fields.
One file_id per dispute. Stripe rejects with
400 "That file is already attached to something else"
if you try to reuse a
file_id
across disputes (especially for
service_documentation
). When fighting N disputes for the same customer, upload N copies of every shared PDF — same content, fresh
file_id
each time.
文件需上传至
files.stripe.com
,而非
api.stripe.com
——不同域名:
bash
curl -s -u "$STRIPE_SECRET_KEY:" \
  -F "purpose=dispute_evidence" \
  -F "file=@$FOLDER/activity_log.pdf" \
  https://files.stripe.com/v1/files
返回结果为
{"id": "file_xxx", ...}
。需记录
id
——这是后续在证据字段中引用的标识。
每个争议对应一个file_id。若尝试跨争议复用
file_id
(尤其是
service_documentation
类型),Stripe会返回
400 "That file is already attached to something else"
错误。当同一客户存在N个争议时,需上传N份相同PDF副本——内容一致,但每次生成新的
file_id

9. Submit evidence (one shot —
submit=true
is final)

9. 提交证据(仅一次机会——
submit=true
为最终操作)

bash
curl -s -u "$STRIPE_SECRET_KEY:" \
  -X POST "https://api.stripe.com/v1/disputes/$DISPUTE_ID" \
  -d "evidence[uncategorized_text]=$REBUTTAL_TEXT" \
  -d "evidence[uncategorized_file]=$ACTIVITY_LOG_FILE_ID" \
  -d "evidence[receipt]=$INVOICE_FILE_ID" \
  -d "evidence[cancellation_policy]=$TERMS_FILE_ID" \
  -d "evidence[cancellation_policy_disclosure]=$CANCEL_DISCLOSURE_TEXT" \
  -d "evidence[refund_policy]=$TERMS_FILE_ID" \
  -d "evidence[refund_policy_disclosure]=$REFUND_DISCLOSURE_TEXT" \
  -d "evidence[cancellation_rebuttal]=$CANCEL_REBUTTAL_TEXT" \
  -d "evidence[access_activity_log]=$ACCESS_LOG_SUMMARY" \
  -d "evidence[service_date]=$SERVICE_START_DATE" \
  -d "evidence[product_description]=$PRODUCT_DESCRIPTION" \
  -d "evidence[customer_email_address]=$CUSTOMER_EMAIL" \
  -d "evidence[customer_name]=$CUSTOMER_NAME" \
  -d "evidence[customer_purchase_ip]=$PURCHASE_IP" \
  -d "evidence[billing_address]=$BILLING_ADDRESS" \
  -d "submit=true" \
  "https://api.stripe.com/v1/disputes/$DISPUTE_ID"
Verify the response:
  • status
    should be
    under_review
  • evidence_details.has_evidence
    should be
    true
  • evidence_details.submission_count
    should be
    1
bash
curl -s -u "$STRIPE_SECRET_KEY:" \
  -X POST "https://api.stripe.com/v1/disputes/$DISPUTE_ID" \
  -d "evidence[uncategorized_text]=$REBUTTAL_TEXT" \
  -d "evidence[uncategorized_file]=$ACTIVITY_LOG_FILE_ID" \
  -d "evidence[receipt]=$INVOICE_FILE_ID" \
  -d "evidence[cancellation_policy]=$TERMS_FILE_ID" \
  -d "evidence[cancellation_policy_disclosure]=$CANCEL_DISCLOSURE_TEXT" \
  -d "evidence[refund_policy]=$TERMS_FILE_ID" \
  -d "evidence[refund_policy_disclosure]=$REFUND_DISCLOSURE_TEXT" \
  -d "evidence[cancellation_rebuttal]=$CANCEL_REBUTTAL_TEXT" \
  -d "evidence[access_activity_log]=$ACCESS_LOG_SUMMARY" \
  -d "evidence[service_date]=$SERVICE_START_DATE" \
  -d "evidence[product_description]=$PRODUCT_DESCRIPTION" \
  -d "evidence[customer_email_address]=$CUSTOMER_EMAIL" \
  -d "evidence[customer_name]=$CUSTOMER_NAME" \
  -d "evidence[customer_purchase_ip]=$PURCHASE_IP" \
  -d "evidence[billing_address]=$BILLING_ADDRESS" \
  -d "submit=true" \
  "https://api.stripe.com/v1/disputes/$DISPUTE_ID"
验证返回结果:
  • status
    应为
    under_review
  • evidence_details.has_evidence
    应为
    true
  • evidence_details.submission_count
    应为
    1

Evidence Strategy by Dispute Reason

按争议类型制定证据策略

fraudulent

fraudulent
(欺诈)

Goal: prove the cardholder made the purchase.
  • Prior undisputed payments on the same card (strongest)
  • OAuth login (Google/Apple) = identity-verified signup
  • Consistent IP / country / device across sessions
  • Multiple checkout attempts before purchase = real person deliberating
  • Stripe's own risk assessment was
    normal
  • Subscription still active and not cancelled
目标:证明持卡人完成了购买。
  • 同一卡片此前无争议的付款记录(最强证据)
  • OAuth登录(Google/Apple)= 身份验证过的注册
  • 会话间IP/国家/设备一致
  • 购买前多次结账尝试=真实用户的决策过程
  • Stripe自身风险评估为
    normal
  • 订阅仍处于活跃状态未取消

product_not_received

product_not_received
(未收到商品)

Goal: prove delivery + use.
  • Login activity log
  • Items created / actions taken inside the product
  • The customer's own self-reported cancel reason, if they cancelled — quoted verbatim against the dispute claim
  • Receipt and welcome email
目标:证明已交付并被使用。
  • 登录活动日志
  • 产品内创建的内容/执行的操作
  • 客户自行填写的取消原因(若已取消)——逐字引用反驳争议主张
  • 收据及欢迎邮件

product_unacceptable

product_unacceptable
(商品不合格)

Goal: show the product matched its description and the customer used it.
  • Same as
    product_not_received
    PLUS your terms-of-service language about quality / refund policy
  • Highlight that customer never opened a support ticket
目标:证明产品符合描述且客户已使用。
  • product_not_received
    相同的证据,加上服务条款中关于质量/退款政策的内容
  • 强调客户从未提交过支持工单

subscription_canceled

subscription_canceled
(已取消订阅)

Goal: prove the customer never cancelled (or cancelled after the renewal).
  • Subscription object showing
    cancel_at_period_end=false
    at the renewal date
  • All login/use activity from after the renewal date
  • Terms language stating annual renewals require explicit cancellation
目标:证明客户从未取消(或在续费后才取消)。
  • 订阅对象显示续费日期时
    cancel_at_period_end=false
  • 续费日期后的所有登录/使用活动
  • 条款中说明年度续费需明确取消的内容

Rebuttal Templates

申诉模板

uncategorized_text

uncategorized_text

[Customer name] created a [Product name] account on [date] via [auth method] and subscribed to [plan] ($[amount]/[interval]) using the same [card brand]. The first [N] payment(s) were never disputed. The customer actively used the service: [N] login sessions from [country] on [device], [N] items created ([list]), and [N] [units] consumed. The disputed charge is the [renewal/initial] payment on [date]. The subscription was [status] and remains [active/cancelled]. The customer never contacted support to cancel or request a refund. Our cancellation and refund policies are published at [TERMS_URL]. This is not a fraudulent transaction — it is a legitimate purchase from the cardholder who [made/has made] [N] other undisputed payments on this account.
[客户姓名]于[日期]通过[认证方式]创建了[产品名称]账户,并订阅了[套餐]($[金额]/[周期]),使用的是同一张[卡片品牌]卡片。前[N]次付款均无争议。客户积极使用服务:[N]次来自[国家]的[设备]登录会话、创建了[N]个内容([列表])、消耗了[N]个[单位]。争议收费为[续费/首次]付款,日期为[日期]。订阅当前状态为[状态],且仍处于[活跃/已取消]状态。客户从未联系支持团队要求取消或退款。我们的取消和退款政策发布于[TERMS_URL]。此交易并非欺诈——是持卡人的合法购买行为,该账户已有[N]次无争议付款记录。

cancellation_policy_disclosure

cancellation_policy_disclosure

Our cancellation policy is disclosed at [TERMS_URL]. Subscribers may cancel at any time and retain access through the end of their billing cycle. This customer never cancelled.
我们的取消政策公示于[TERMS_URL]。订阅用户可随时取消,并在计费周期结束前保留访问权限。该客户从未取消订阅。

refund_policy_disclosure

refund_policy_disclosure

Our refund policy is disclosed at [TERMS_URL]. We offer a [N]-day money-back guarantee. The customer did not request a refund within that window, nor at any time.
我们的退款政策公示于[TERMS_URL]。我们提供[N]天无理由退款保障。客户未在该期限内及任何时间申请退款。

Important Notes

重要提示

  • File uploads go to
    files.stripe.com
    , NOT
    api.stripe.com
  • One submission per dispute.
    submit=true
    is final
  • Evidence deadline is
    evidence_details.due_by
    (unix timestamp). After that you can no longer submit
  • Database queries must be READ-ONLY — restrict the connection's role if possible
  • Never include other customers' data in the activity log PDF
  • Save every evidence package to disk in case you need to reference it for future disputes from the same customer
  • 文件需上传至
    files.stripe.com
    ,而非
    api.stripe.com
  • 每个争议仅可提交一次。
    submit=true
    为最终操作
  • 证据提交截止时间为
    evidence_details.due_by
    (Unix时间戳),逾期无法提交
  • 数据库查询必须为只读——尽可能限制连接角色权限
  • 活动日志PDF中绝不能包含其他客户的数据
  • 将所有证据包保存至本地,以便后续应对同一客户的争议时参考

Pattern That Wins

胜诉模式

The single most reliable winning pattern observed across same-day-cancellation disputes:
Customer signs up, uses product briefly, cancels within hours citing "Poor user experience" in your in-app cancel form, then files a chargeback days later claiming "product not received."
The cancel form's reason — recorded in your own database — directly contradicts the chargeback claim. Quote it word-for-word in the rebuttal. This evidence pattern has won within ~30 days of submission with full amount + dispute fee returned.
Always check
users.cancel_reason
(or your equivalent) FIRST when the dispute reason is
product_not_received
or
product_unacceptable
.
在当日取消争议中,最可靠的胜诉模式如下:
客户注册,短暂使用产品,数小时内通过应用内取消表单填写「用户体验差」并取消,随后数天提交拒付申请,声称「未收到商品」。
取消表单中的理由——记录在你的数据库中——直接与拒付主张矛盾。需在申诉中逐字引用。此证据模式提交后约30天即可胜诉,全额返还金额及争议费用。
当争议理由为
product_not_received
product_unacceptable
时,务必首先检查
users.cancel_reason
(或等效字段)。