Guides
Concepts
Before integrating RecurCite, it helps to understand how Stripe disputes work, what Compelling Evidence 3.0 changes, and how RecurCite transforms your application data into winning evidence.
Understanding Stripe disputes
A dispute (also called a chargeback) happens when a customer contacts their bank to reverse a charge. Stripe notifies you via a charge.dispute.created webhook. From that moment, you have a limited window — typically 7 to 21 days — to submit evidence proving the charge was legitimate.
Dispute lifecycle
| Stage | What happens | Timeline |
|---|---|---|
| 1. Opened | Customer files a dispute with their bank. Stripe debits the disputed amount + a $15 fee from your account. | Day 0 |
| 2. Evidence due | You must submit evidence to Stripe before the deadline. If you miss it, the bank rules in the customer's favor by default. | 7–21 days |
| 3. Bank review | The issuing bank reviews your evidence and makes a decision. This is final — there is no appeal. | 60–75 days |
| 4. Outcome | Won: Funds + $15 fee returned. Lost: You keep the debit. Either way, the dispute counts toward your dispute rate. | — |
Why most merchants lose
The average merchant wins only about 30-40% of disputed chargebacks. The top reasons for losing:
- No evidence submitted — many merchants miss the deadline or don't know what to provide.
- Weak evidence — generic screenshots or customer service logs without timestamps, IP addresses, or usage proof.
- Wrong evidence format — Stripe has specific evidence fields (e.g.,
cancellation_rebuttal,service_documentation) that most merchants don't know about. - No pre-dispute data collection — by the time you need evidence, it's too late to start collecting it.
Tip
RecurCite solves this by collecting evidence before disputes happen. When a dispute arrives, you already have the data you need.
Compelling Evidence 3.0 (CE3)
Visa Compelling Evidence 3.0 is a dispute resolution program introduced by Visa that can shift liability back to the issuing bank before the dispute even reaches the traditional evidence review stage. This is RecurCite's most powerful feature.
How CE3 works
CE3 works by proving that the person who made the disputed transaction is the same person who made previous, undisputed transactions. If the same device, IP address, or email was used for prior legitimate charges, the liability shifts.
CE3 signal matching flow
Collect signals
On every successful charge, RecurCite captures IP address, email, and device fingerprint via the SDK.
Hash & encrypt
Signals used for CE3 matching are SHA-256 hashed and encrypted at rest. Raw emails are rejected.
Match on dispute
When a dispute arrives, RecurCite finds 2+ prior undisputed transactions with matching signals and auto-populates the CE3 evidence.
CE3 requirements
For a dispute to qualify for CE3 liability shift, you need:
| Requirement | Details |
|---|---|
| At least 2 prior undisputed transactions | From the same customer, completed successfully and never disputed |
| Within 120–365 days | Prior transactions must fall within this window relative to the disputed charge |
| At least 1 matching signal | IP address or email address must match between the prior transactions and the disputed transaction |
| Visa card network | CE3 is a Visa-specific program (Mastercard has similar but separate rules) |
How to enable CE3
Send transaction.completed events with IP, email, and device fingerprint on every successful charge. See the Event Reference → transaction.completed for the full field list.
How RecurCite builds evidence
RecurCite automates the entire evidence lifecycle, from data collection to Stripe submission. Here's the flow:
Evidence Events
Your app sends timestamped evidence events (ToS acceptance, logins, usage, cancellations) via the SDK or REST API. Events are validated, stored, and linked to Stripe customers.
Dispute Arrives
When Stripe sends a charge.dispute.created webhook, RecurCite automatically collects all matching evidence events for that customer.
Bundle Generation
RecurCite assembles a Bundle — a structured collection of facts, citations (linked to specific events), a chronological timeline, and an Evidence Health score (0–100).
Packet Creation
The Bundle is rendered into a branded PDF Packet with a cover page, narrative, timeline visualization, and appendix. This is the document banks actually review.
Stripe Submission
RecurCite uploads the PDF to Stripe's Files API, maps your evidence to Stripe's evidence fields, and submits with an idempotency key. Everything is audit-logged.
Evidence Health
Every Bundle gets an Evidence Health score from 0 to 100 measuring how complete your evidence is. The score is based on which evidence types you've sent:
- Terms acceptance — strongest single piece of evidence
- Login history — proves the customer accessed their account
- Product usage — proves the customer received value
- Cancellation flow — proves you offered an easy way to cancel
- Support interactions — proves you addressed concerns
- CE3 signals — enables Visa liability shift
Proof Discount
Maintain an Evidence Health grade of A (80+) on 80% or more of your disputes to qualify for reduced success fees. See Pricing → Proof Discount.
Assist Mode vs. Autopilot
Assist Mode
You review each Bundle before submission. Ideal for getting started or when you want full control.
- Review evidence before submission
- Edit or add notes to Bundles
- Available on all plans
Autopilot
RecurCite generates and submits evidence automatically when a dispute arrives. Zero manual work.
- Instant response — no delay
- Best for high dispute volumes
- Available on Pro and Scale plans
Test mode
Test mode lets you verify your integration without affecting production data. Use your rc_test_* API key to send test events.
Testing with Stripe CLI
Use the Stripe CLI to simulate disputes locally:
# 1. Forward webhooks to your local server
stripe listen --forward-to localhost:3000/api/stripe/connect-webhook
# 2. In another terminal, trigger a test dispute
stripe trigger charge.dispute.created
# 3. Check your RecurCite dashboard — the dispute should appearVerifying your integration
After sending test events, verify they were received:
- Go to Dashboard → Disputes and find the test dispute
- Click the dispute to see its evidence timeline
- Verify your events appear with correct timestamps and data
- Click Generate Bundle to test evidence assembly
- Review the Evidence Health score — aim for 80+
Note
Test mode events are stored in the same database but flagged as test data. They won't be used for real dispute submissions.
Next steps
- Quickstart — connect Stripe and send your first event in 10 minutes
- API Reference — raw HTTP endpoints with cURL examples
- Stripe Billing Setup — where to add each event type in your billing flow