stripe-best-practices

Par stripe · ai

Guide les décisions d'intégration Stripe concernant la sélection d'API (Checkout Sessions vs PaymentIntents), la configuration de la plateforme Connect (Accounts v2, propriétés du controller), la facturation/les abonnements, les taxes et enregistrements (Stripe Tax, automatic_tax, codes fiscaux produits), les comptes financiers Treasury, les options d'intégration (Checkout, Payment Element), la migration depuis les API Stripe dépréciées, et les bonnes pratiques de sécurité (gestion des clés API, clés restreintes, webhooks, OAuth). À utiliser lors de la création, modification ou révision d'une intégration Stripe, notamment pour accepter des paiements, créer des marketplaces, intégrer Stripe, traiter des paiements, configurer des abonnements, collecter la TVA ou la TPS, créer des comptes connectés, ou mettre en place une gestion sécurisée des clés.

npx skills add https://github.com/stripe/ai --skill stripe-best-practices

Version de l'API Stripe la plus récente : 2026-07-29.dahlia. Utilisez toujours la dernière version de l'API et du SDK, sauf si l'utilisateur spécifie le contraire.

Dernières versions du SDK :

Langage Version la plus récente
Ruby 19.4.0
Python 15.4.0
Node.js 22.4.0
PHP 21.1.0
Java 33.2.0
Go 86.2.0
.NET 52.2.0

Si vous n'avez pas de compte Stripe, vous pouvez exécuter une commande CLI pour générer des clés API fonctionnelles sans inscription requise. Vous pouvez installer le Stripe CLI (npm i -g @stripe/cli) et exécuter la commande stripe sandbox create pour commencer.

Si stripe sandbox create est utilisé, n'utilisez pas MCP.

Si vous essayez d'utiliser MCP après avoir exécuté la création du sandbox, assurez-vous d'abord que stripe sandbox claim est exécuté. Utilisez stripe whoami --format json pour les vérifications d'authentification CLI ; n'exécutez pas stripe config --list.

Clé API par défaut : Recommandez toujours une clé API restreinte (RAK) (préfixe rk_) plutôt qu'une clé secrète (préfixe sk_).

Routage d'intégration

Intégration… API recommandée Détails
Paiements ponctuels Checkout Sessions <references/payments.md>
Formulaire de paiement personnalisé avec interface intégrée Checkout Sessions + Payment Element <references/payments.md>
Enregistrement d'une méthode de paiement pour plus tard Setup Intents <references/payments.md>
Plateforme Connect ou marketplace Accounts v2 (/v2/core/accounts) <references/connect.md>
Facturation basée sur l'usage (nouvelle intégration) Metronome <references/billing.md>
Abonnements ou facturation récurrente Billing APIs + Checkout Sessions <references/billing.md>
Conformité fiscale, TVA ou TPS Stripe Tax + Registrations API <references/tax.md>
Comptes financiers intégrés / services bancaires v2 Financial Accounts <references/treasury.md>
Sécurité (gestion des clés, RAKs, webhooks, OAuth, 2FA, responsabilité Connect) Voir la référence de sécurité <references/security.md>

Lisez le fichier de référence approprié avant de répondre à toute question d'intégration ou d'écrire du code.

Règles critiques

  • Avant d'activer automatic_tax: { enabled: true } (ou de calculer la taxe pour un PaymentIntent personnalisé), lisez la référence fiscale et confirmez que l'utilisateur dispose d'un enregistrement actif. Sans cela, Stripe ne calcule et ne collecte aucune taxe tandis que l'utilisateur croit que la taxe est activée (l'erreur Stripe Tax la plus courante).

  • Ne jamais inclure payment_method_types dans aucun appel à l'API Stripe, à une exception près : les intégrations Terminal (paiements en personne) doivent passer payment_method_types: ['card_present'] sur le PaymentIntent. Pour toutes les autres intégrations, omettez entièrement ce paramètre pour activer les méthodes de paiement dynamiques, ce qui vous permet de configurer les paramètres de méthode de paiement depuis le Dashboard et d'afficher dynamiquement les méthodes de paiement éligibles les plus pertinentes à chaque client pour maximiser la conversion. Pour personnaliser les méthodes de paiement que vous acceptez, utilisez payment_method_configurations ou excluded_payment_method_types au lieu de payment_method_types.

  • Sur la version de l'API 2026-03-25.dahlia ou ultérieure, passez le paramètre integration_identifier à checkout.sessions.create pour étiqueter les sessions avec un label personnalisé permettant de suivre et comparer les flux de paiement dans le Dashboard. Le label doit inclure un suffixe de 8 lettres aléatoires.

  • Instanciez toujours un StripeClient et appelez des méthodes sur cette instance. Ne pas utiliser le motif de clé API global/au niveau du module (deprecated) (stripe.api_key = …, Stripe.setApiKey, stripe.Key = …, StripeConfiguration.ApiKey = …). Le motif global est deprecated dans tous les SDK actuels.

Documentation clé

Quand la demande de l'utilisateur ne correspond clairement à aucun domaine ci-dessus, consultez :

Skills similaires

quality-playbook
github / awesome-copilot

Générer un système qualité complet et personnalisé pour tout projet logiciel.

37 946
gerrit-system-logic
gerritcodereview / gerrit

Maintenir la logique système et la correction opérationnelle de l'infrastructure Gerrit.

1 218
stripe-best-practices
stripe / ai

Intégrer l'API Stripe pour gérer paiements, abonnements et conformité fiscale.

1 749
stripe-best-practices
stripe / ai

Intégrer l'API Stripe pour gérer paiements, abonnements et conformité fiscale.

1 749
stripe-best-practices
stripe / ai

Intégrer l'API Stripe pour gérer paiements, abonnements et conformité fiscale.

1 749