Comment automatiser la gestion des litiges Stripe avec l’historique d’utilisation et les données IP

Webhook Stripe × Logs d’activité = dossier de preuve qui se monte tout seul

Tu vends un produit numérique. Un client ouvre un chargeback. Stripe te donne quelques jours pour répondre. Si tu n’as pas de système en place, tu passes la nuit à chercher des captures d’écran dans tes logs de serveur, à reconstituer manuellement ce que le client a fait, et tu soumets un dossier incomplet à la va-vite. Tu perds. Et tu paies les frais de litige en plus. Ce tutoriel t’enseigne à construire un pipeline automatisé : dès qu’une dispute s’ouvre chez Stripe, ton système collecte l’historique d’utilisation du client, ses données IP, ses connexions et ses actions, et structure tout ça en preuve soumissible. Tu n’as plus à chercher manuellement. Aujourd’hui tu vas apprendre à:

• Configurer un webhook Stripe qui se déclenche à l’ouverture d’une dispute
• Collecter automatiquement les logs d’utilisation et les données IP liés à la transaction contestée
• Structurer les preuves dans le format attendu par Stripe
• Soumettre la réponse via l’API Stripe sans toucher au tableau de bord manuellement
• Éviter les pièges courants qui font perdre des disputes gagnables

Ce dont t’as besoin avant de commencer

1. Un compte Stripe actif avec accès API

Tu as besoin de tes clés API Stripe (secrète et publique). Toutes les opérations de ce tutoriel passent par l’API, pas par le tableau de bord. La clé secrète te donne accès aux endpoints de disputes, de charge et de soumission de preuves.

2. Un serveur capable de recevoir des webhooks

Ton endpoint webhook doit être accessible publiquement via HTTPS. En développement, tu peux utiliser un tunnel comme ngrok ou cloudflared. En production, n’importe quel serveur avec une route HTTP POST fait l’affaire. Le langage importe peu : Node.js, Python, PHP, Go fonctionnent tous.

3. Une base de données de logs d’activité

C’est le prérequis le plus important. Si tu n’enregistres pas déjà les connexions, les actions et les téléchargements de tes utilisateurs avec des timestamps et des adresses IP, l’automatisation ne peut rien inventer. Tu as besoin de logs fiables qui couvrent au moins la période autour de la transaction contestée.

4. Accès à la Stripe Webhook Secret

Stripe te fournit un secret de signature pour chaque endpoint webhook enregistré. Tu en as besoin pour valider que les événements entrants proviennent vraiment de Stripe et pas d’un tiers malveillant.

5. Connaissance de base de l’API Stripe Disputes

Stripe expose des endpoints pour lire les détails d’une dispute (/v1/disputes/{id}), pour mettre à jour les preuves (/v1/disputes/{id} via PATCH) et pour soumettre le dossier. La documentation officielle de Stripe couvre tous ces endpoints en détail.

Le workflow, étape par étape

La première chose à comprendre sur les webhooks Stripe : chaque requête entrante contient une signature dans le header Stripe-Signature. Si tu ne valides pas cette signature, n’importe qui peut envoyer une fausse notification de dispute à ton serveur et déclencher ton pipeline sur une transaction qui n’t existe pas. Stripe te donne un secret de signature spécifique à ton endpoint. Tu utilises ce secret et la bibliothèque Stripe officielle pour ta plateforme pour construire la signature attendue et la comparer à celle reçue. Si elles ne correspondent pas, tu retournes un 400 et tu ignores la requête.

import stripe
from flask import Flask, request, jsonify
app = Flask(__name__)
STRIPE_WEBHOOK_SECRET = "whsec_ton_secret_ici"
@app.route("/webhook/stripe", methods=["POST"])
def stripe_webhook():
payload = request.get_data()
sig_header = request.headers.get("Stripe-Signature")
try:
event = stripe.Webhook.construct_event(
payload, sig_header, STRIPE_WEBHOOK_SECRET
)
except ValueError:
# Payload invalide
return jsonify({"error": "Invalid payload"}), 400
except stripe.error.SignatureVerificationError:
# Signature invalide, rejette immédiatement
return jsonify({"error": "Invalid signature"}), 400
if event["type"] == "charge.dispute.created":
dispute = event["data"]["object"]
handle_new_dispute(dispute)
return jsonify({"status": "ok"}), 200
def handle_new_dispute(dispute):
# Ici démarre ton pipeline de collecte de preuves
charge_id = dispute.get("charge")
dispute_id = dispute.get("id")
# Lance la collecte asynchrone pour ne pas bloquer le webhook
collect_evidence_for_dispute.delay(dispute_id, charge_id)

Une règle critique : ton endpoint webhook doit retourner un 200 rapidement. Stripe considère que ton endpoint est en panne si tu tardes trop à répondre, et peut retenter l’envoi. Lance la collecte de données en tâche asynchrone (Celery, Bull, une queue quelconque) et réponds immédiatement.

Une fois le charge_id en main, tu appelles l’API Stripe pour récupérer tous les détails de la charge originale. Ce qui t’intéresse particulièrement : les métadonnées que tu as toi-même attachées à la charge au moment du paiement. C’est là que beaucoup de développeurs ratent une opportunité. Si tu n’attaches pas de métadonnées à tes charges Stripe (comme l’identifiant utilisateur interne, l’identifiant de session, ou l’identifiant de commande), tu dois faire une jointure approximative sur l’email ou le montant pour retrouver le bon utilisateur dans ta base de données. Ça marche, mais c’est fragile. La bonne pratique : à la création de chaque charge Stripe, ajoute metadata avec au minimum ton user_id interne. Quand la dispute arrive, tu peux aller directement au bon enregistrement.

import stripe
stripe.api_key = "sk_live_ton_api_key"
def get_charge_details(charge_id: str) -> dict:
charge = stripe.Charge.retrieve(charge_id)
return {
"charge_id": charge.id,
"amount": charge.amount,
"currency": charge.currency,
"created": charge.created, # timestamp Unix
"customer_email": charge.billing_details.email,
"customer_name": charge.billing_details.name,
# Tes métadonnées internes
"user_id": charge.metadata.get("user_id"),
"order_id": charge.metadata.get("order_id"),
"session_id": charge.metadata.get("session_id"),
# IP au moment du paiement (si tu l'as passée)
"payment_method_details": charge.payment_method_details,
}

C’est la viande du dossier. Stripe veut voir que l’utilisateur a effectivement utilisé ce qu’il a payé. Tes logs d’activité doivent démontrer ça de façon claire et chronologique. Ce que tu cherches à construire : une timeline d’actions avec timestamps précis. Connexion initiale après le paiement, accès aux fonctionnalités payantes, téléchargements de fichiers, engagement avec le contenu. Chaque entrée doit avoir un timestamp, un type d’action, et idéalement l’adresse IP associée.

from datetime import datetime, timezone
import json
def collect_usage_logs(user_id: str, charge_created_timestamp: int) -> dict:
"""
Collecte les logs d'utilisation pour un utilisateur
depuis la date de la charge jusqu'à maintenant.
"""
# Convertis le timestamp Stripe en datetime
charge_date = datetime.fromtimestamp(charge_created_timestamp, tz=timezone.utc)
# Requête à adapter selon ton ORM/DB
# Exemple pseudo-code pour une base SQL classique
logs = db.query("""
SELECT 
action_type,
ip_address,
user_agent,
resource_accessed,
created_at
FROM activity_logs
WHERE 
user_id = %s
AND created_at >= %s
ORDER BY created_at ASC
LIMIT 200
""", (user_id, charge_date))
# Structure les logs pour Stripe
formatted_logs = []
for log in logs:
formatted_logs.append({
"timestamp": log.created_at.isoformat(),
"action": log.action_type,
"ip": log.ip_address,
"resource": log.resource_accessed,
"user_agent": log.user_agent
})
summary = {
"user_id": user_id,
"total_actions": len(formatted_logs),
"first_access": formatted_logs[0]["timestamp"] if formatted_logs else None,
"last_access": formatted_logs[-1]["timestamp"] if formatted_logs else None,
"unique_ips": list(set(log["ip"] for log in formatted_logs)),
"action_types": list(set(log["action"] for log in formatted_logs)),
"raw_logs": formatted_logs
}
return summary

Le résumé (summary) que tu génères ici sera utilisé pour rédiger la description textuelle de tes preuves dans le champ customer_communication et service_documentation de Stripe. Le journal brut sera formaté en document PDF ou texte à attacher comme fichier.

Les données IP servent un objectif précis dans le dossier de dispute : montrer que les accès au service ont eu lieu depuis des appareils et des emplacements cohérents avec le profil du client. Un utilisateur qui conteste « je n’ai jamais reçu le service » mais dont les logs montrent des connexions répétées depuis la même IP résidentielle, c’est difficile à maintenir. Ce que tu veux documenter :

• L’IP utilisée au moment du paiement (si tu l’as capturée, ce que tu devrais faire)
• Les IPs utilisées lors des connexions subséquentes
• La cohérence géographique entre ces IPs (même ville, même FAI)
• Le user agent (navigateur et OS) pour montrer la continuité d’accès Un outil de géolocalisation IP (MaxMind GeoLite2, ip-api.com, ou équivalent) te permet d’enrichir chaque IP avec pays, région, ville et organisation (FAI). Ça rend le dossier plus lisible pour l’analyste Stripe : au lieu d’une liste de chaînes comme 192.168.x.x, tu montres « Montréal, QC, Canada, Vidéotron Ltée » de façon cohérente sur plusieurs sessions.

import requests
from collections import Counter
def analyze_ip_data(ip_list: list, payment_ip: str = None) -> dict:
"""
Analyse les adresses IP collectées et génère un résumé
formaté pour le dossier de dispute Stripe.
"""
enriched_ips = []
for ip in set(ip_list): # Dédupliquer
try:
# ip-api.com : gratuit pour usage non-commercial limité
# Vérifie les conditions de ta solution choisie
response = requests.get(
f"http://ip-api.com/json/{ip}",
timeout=3
).json()
enriched_ips.append({
"ip": ip,
"country": response.get("country"),
"region": response.get("regionName"),
"city": response.get("city"),
"isp": response.get("isp"),
"org": response.get("org"),
})
except Exception:
enriched_ips.append({"ip": ip, "error": "lookup failed"})
cities = [e.get("city") for e in enriched_ips if e.get("city")]
isps = [e.get("isp") for e in enriched_ips if e.get("isp")]
summary_text = f"""
ANALYSE DES ACCÈS IP
IPs uniques détectées: {len(set(ip_list))}
Accès total: {len(ip_list)}
Villes détectées: {", ".join(set(cities))}
FAI/Organisation: {", ".join(set(isps))}
"""
if payment_ip:
payment_ip_info = next(
(e for e in enriched_ips if e["ip"] == payment_ip), None
)
if payment_ip_info:
summary_text += f"""
IP au moment du paiement: {payment_ip}
→ {payment_ip_info.get('city')}, {payment_ip_info.get('region')}, {payment_ip_info.get('country')}
→ {payment_ip_info.get('isp')}
Cohérence géographique: Les accès subséquents proviennent de la même région géographique que le paiement.
"""
return {
"enriched_ips": enriched_ips,
"summary": summary_text,
"unique_count": len(set(ip_list)),
"consistent_location": len(set(cities)) <= 3 # Heuristique simple
}

Stripe structure sa réponse à une dispute autour de plusieurs champs de preuve distincts. Chacun correspond à un type d’information que tu peux soumettre. Les plus pertinents pour les produits numériques :

• customer_email_address : l’email confirmé du client
• customer_name : nom complet selon tes données d’inscription
• customer_ip_address : IP au moment de l’inscription ou du paiement
• customer_signature : si tu as un log d’acceptation de CGU avec timestamp
• service_date : date à laquelle le service a été rendu
• service_documentation : fichier attaché qui documente le service fourni (ton log d’utilisation en PDF)
• customer_communication : captures ou logs de communication avec le client
• refund_policy_disclosure : texte ou lien vers ta politique de remboursement
• uncategorized_text : texte libre pour tout ce qui ne rentre pas ailleurs Le document principal que tu génères est le service_documentation. Construis-le comme un rapport structuré : entête avec les informations de la transaction, timeline des accès, analyse IP, liste des actions effectuées. Une page bien organisée avec des timestamps clairs est plus persuasive qu’un dump de logs bruts de cinquante pages.

import stripe
from io import BytesIO
from reportlab.pdfgen import canvas # pip install reportlab
from datetime import datetime, timezone
def generate_evidence_pdf(
charge_details: dict,
usage_logs: dict,
ip_analysis: dict
) -> bytes:
"""
Génère un PDF structuré comme preuve de service pour Stripe.
"""
buffer = BytesIO()
c = canvas.Canvas(buffer)
# En-tête
c.setFont("Helvetica-Bold", 14)
c.drawString(50, 800, "PREUVE DE SERVICE FOURNI")
c.setFont("Helvetica", 10)
c.drawString(50, 780, f"Dispute ID: {charge_details.get('dispute_id', 'N/A')}")
c.drawString(50, 765, f"Charge ID: {charge_details.get('charge_id', 'N/A')}")
c.drawString(50, 750, f"Client: {charge_details.get('customer_email', 'N/A')}")
c.drawString(50, 735, f"Date de la transaction: {charge_details.get('charge_date', 'N/A')}")
# Section logs
c.setFont("Helvetica-Bold", 12)
c.drawString(50, 700, "HISTORIQUE D'UTILISATION")
c.setFont("Helvetica", 9)
y_pos = 680
c.drawString(50, y_pos, f"Actions totales enregistrées: {usage_logs.get('total_actions', 0)}")
y_pos -= 15
c.drawString(50, y_pos, f"Premier accès après paiement: {usage_logs.get('first_access', 'N/A')}")
y_pos -= 15
c.drawString(50, y_pos, f"Dernier accès: {usage_logs.get('last_access', 'N/A')}")
y_pos -= 15
c.drawString(50, y_pos, f"Types d'actions: {', '.join(usage_logs.get('action_types', []))}")
y_pos -= 30
c.setFont("Helvetica-Bold", 10)
c.drawString(50, y_pos, "Détail des 20 premières actions:")
c.setFont("Helvetica", 8)
for log in usage_logs.get("raw_logs", [])[:20]:
y_pos -= 13
if y_pos < 50:
c.showPage()
y_pos = 780
c.drawString(50, y_pos, 
f"{log['timestamp']} | {log['action']} | {log['ip']}"
)
# Section IP
c.showPage()
c.setFont("Helvetica-Bold", 12)
c.drawString(50, 800, "ANALYSE DES DONNÉES IP")
c.setFont("Helvetica", 9)
y_pos = 780
summary_lines = ip_analysis.get("summary", "").split("\n")
for line in summary_lines:
c.drawString(50, y_pos, line)
y_pos -= 13
c.save()
buffer.seek(0)
return buffer.read()
def submit_dispute_evidence(
dispute_id: str,
charge_details: dict,
usage_logs: dict,
ip_analysis: dict
) -> bool:
"""
Soumet les preuves à Stripe via l'API.
"""
# Génère le PDF
pdf_bytes = generate_evidence_pdf(charge_details, usage_logs, ip_analysis)
# Upload le fichier vers Stripe
uploaded_file = stripe.File.create(
purpose="dispute_evidence",
file=("evidence.pdf", pdf_bytes, "application/pdf"),
)
description_text = f"""
Le client {charge_details.get('customer_email')} a souscrit à notre service et y a accédé activement.
Notre système enregistre {usage_logs.get('total_actions', 0)} actions distinctes depuis son compte après le paiement.
Le premier accès a eu lieu le {usage_logs.get('first_access')}, suivi d'utilisations régulières documentées dans le fichier joint.
Les accès proviennent d'adresses IP cohérentes avec son profil géographique, détaillées dans le rapport en pièce jointe.
Le service souscrit a été intégralement fourni comme décrit au moment de l'achat.
""".strip()
# Met à jour la dispute avec les preuves
stripe.Dispute.modify(
dispute_id,
evidence={
"customer_email_address": charge_details.get("customer_email"),
"customer_name": charge_details.get("customer_name"),
"customer_ip_address": ip_analysis.get("enriched_ips", [{}])[0].get("ip"),
"service_date": charge_details.get("charge_date"),
"service_documentation": uploaded_file.id,
"uncategorized_text": description_text,
},
submit=True # True = soumet immédiatement, False = sauvegarde en brouillon
)
return True

Le paramètre submit=True est critique. Si tu le laisses à False, les preuves sont sauvegardées en brouillon mais ne sont pas soumises à Stripe. Tu dois passer à True pour que ton dossier soit officiellement reçu.

import logging
from datetime import datetime, timezone
logger = logging.getLogger(__name__)
def collect_evidence_for_dispute(dispute_id: str, charge_id: str):
"""
Pipeline complet : appelée par ta queue asynchrone.
"""
try:
logger.info(f"Début collecte de preuves pour dispute {dispute_id}")
# Étape 1: Détails de la charge
charge_details = get_charge_details(charge_id)
charge_details["dispute_id"] = dispute_id
charge_details["charge_date"] = datetime.fromtimestamp(
charge_details.get("created", 0), tz=timezone.utc
).strftime("%Y-%m-%d %H:%M:%S UTC")
user_id = charge_details.get("user_id")
if not user_id:
logger.warning(f"Pas de user_id dans les métadonnées de la charge {charge_id}")
# Essaie de retrouver par email comme fallback
user_id = find_user_by_email(charge_details.get("customer_email"))
if not user_id:
logger.error(f"Impossible d'identifier l'utilisateur pour {charge_id}")
return False
# Étape 2: Logs d'utilisation
usage_logs = collect_usage_logs(
user_id=user_id,
charge_created_timestamp=charge_details.get("created")
)
logger.info(f"Collecté {usage_logs['total_actions']} actions pour {user_id}")
# Étape 3: Analyse IP
all_ips = usage_logs.get("unique_ips", [])
payment_ip = charge_details.get("payment_ip") # Si tu l'enregistres
ip_analysis = analyze_ip_data(all_ips, payment_ip)
# Étape 4: Soumission
success = submit_dispute_evidence(
dispute_id=dispute_id,
charge_details=charge_details,
usage_logs=usage_logs,
ip_analysis=ip_analysis
)
if success:
logger.info(f"Dispute {dispute_id} : preuves soumises avec succès")
# Notifie ton équipe
notify_team_dispute_submitted(dispute_id, usage_logs["total_actions"])
return success
except Exception as e:
logger.error(f"Erreur pipeline dispute {dispute_id}: {str(e)}", exc_info=True)
# Alerte immédiate en cas d'erreur : une dispute non traitée = perte garantie
alert_team_dispute_error(dispute_id, str(e))
return False

Le hic

Soyons clairs sur ce que ce système ne peut pas faire. Ça ne fonctionne que si tu as des logs fiables. Si ton application n’enregistre pas les actions utilisateur avec des timestamps précis et des adresses IP, le pipeline collecte… rien d’utile. L’automatisation amplifie ce que tu as déjà. Elle ne crée pas de preuves qui n’existent pas. Si tu pars de zéro, tu dois d’abord implémenter la journalisation dans ton app, attendre d’avoir des données, et ensuite seulement déployer ce pipeline. Les disputes pour « article non reçu » sur du physique, c’est un autre terrain. Ce workflow est optimisé pour les produits numériques avec des logs d’accès clairs : SaaS, cours en ligne, logiciels, contenus téléchargeables. Si tu vends du physique, tu as besoin de numéros de suivi et de confirmations de livraison, pas de logs IP. Stripe ne garantit jamais une issue favorable. Même avec un dossier béton, la banque émettrice a le dernier mot sur certaines catégories de disputes. Les raisons de dispute comme « transaction non autorisée » impliquent souvent un vrai problème de fraude sur la carte du client, pas une mauvaise foi du client lui-même. Dans ces cas-là, tu peux perdre même avec de bonnes preuves. Le délai de soumission est strict. Stripe donne un délai fixe pour répondre à une dispute, et ce délai varie selon le type de carte et la raison de la dispute. Si ton webhook est en panne pendant quelques jours et que tu rates la fenêtre, les preuves que tu soumets après la deadline ne sont pas examinées. Surveille ton endpoint webhook activement. La géolocalisation IP n’est pas parfaite. Les VPNs, les proxies, les réseaux d’entreprise et les connexions mobiles itinérantes peuvent montrer des IPs « incohérentes » qui n’indiquent aucune fraude. Présente les données IP comme un élément corroborant parmi d’autres, pas comme preuve centrale. La bibliothèque reportlab pour le PDF demande une configuration. L’exemple de code ci-dessus est fonctionnel mais basique. Un PDF plus professionnel avec tables, logo et mise en page soignée demande du travail supplémentaire. Tu peux aussi générer du HTML et le convertir en PDF via weasyprint ou un service externe si tu préfères.

Quelques trucs bons à savoir

• Enregistre l’IP au moment du paiement. Quand tu crées une PaymentIntent ou une Charge, tu peux passer des métadonnées. Enregistre l’IP du client au moment du checkout dans tes propres tables, pas seulement dans Stripe.
• Les métadonnées Stripe sont ton pont. Attache toujours user_id et order_id à chaque charge via le champ metadata. Sans ça, la liaison entre la dispute Stripe et ton utilisateur interne devient une recherche approximative.
• Teste ton webhook en mode test Stripe. Stripe offre un mode test où tu peux déclencher manuellement des événements de dispute via le tableau de bord ou l’API. Utilise-le pour valider ton pipeline avant de le déployer en production.
• Surveille les événements charge.dispute.funds_withdrawn. Quand Stripe débite ton compte en réponse à une dispute, tu veux le savoir immédiatement, même si le pipeline a déjà soumis les preuves. C’est un signal que le processus est avancé.
• Les frais standards Stripe au Canada sont de 2,9 % + 0,30 CAD par transaction. Une dispute perdue te coûte ce montant en plus des frais de litige. Sur un volume important de transactions, même un taux de victoire modeste sur tes disputes représente un retour concret.
• Garde tes logs pendant au moins un an. Les délais de rétrofacturation varient et certains litiges apparaissent longtemps après la transaction initiale. Des logs qui expirent après quelques semaines te laissent sans preuve pour les disputes tardives.
• L’événement charge.dispute.updated te signale les changements de statut d’une dispute. Abonne-toi aussi à cet événement pour suivre l’issue de chaque dossier soumis et ajuster ton pipeline si certains types de preuves fonctionnent mieux que d’autres.
• Stripe Tax calcule automatiquement TPS, TVQ et VAT, pour un coût additionnel de 0,5 % par transaction taxable. Si tu es une entreprise québécoise, ça simplifie la conformité fiscale sur les mêmes transactions que tu sécurises avec ce pipeline.

Check-list finale

Verdict + prochaines étapes

Ce pipeline est pertinent si tu vends des produits numériques avec des logs d’activité fiables. La mise en place demande quelques heures de développement, mais une fois en production, chaque dispute déclenche automatiquement la collecte et la soumission de preuves sans intervention manuelle. La prochaine étape concrète : commence par vérifier que tes logs d’activité actuels contiennent des adresses IP et des timestamps pour chaque action utilisateur. Si ce n’est pas le cas, implante ça en priorité. Le webhook et la soumission peuvent attendre, les logs doivent précéder la transaction que tu vas devoir défendre.

Texte par David Cyr

David Cyr

L'Opérateur AI · Fondateur Taverne AI

Opérateur québécois. J'ai construit LeadLoup, un mandat acheteur véhicules pour Complexe Kia, et plusieurs systèmes IA en production. À la Taverne, je teste des outils qu'on me paie pour utiliser, et je dis si c'est utile ou si c'est de la marde.

À propos·Méthodologie