Checklist d'intégration de passerelle de paiement

L'intégration des paiements paraît simple dans le guide de démarrage rapide — et devient complexe dès que de l'argent réel circule. La démo accepte une carte et retourne un succès. En production, il y a des paiements échoués, des litiges, des remboursements, des cas limites liés aux devises, et un webhook qui arrive deux fois. Cette checklist couvre ce qui distingue une intégration de démonstration d'une intégration sur laquelle vous pouvez compter pour vos revenus.

Ne laissez jamais les données de carte transiter par votre serveur

La règle la plus importante : les données de carte doivent aller directement du navigateur vers le processeur, sans jamais passer par votre backend. Utilisez des champs hébergés ou un checkout hébergé — le Payment Element ou le Checkout de Stripe, ou l'équivalent chez votre prestataire. Cela vous maintient dans le niveau de conformité PCI le plus léger et élimine d'emblée toute une catégorie de failles.

Si vous stockez des numéros de carte bruts, arrêtez et repensez votre architecture. Il n'y a presque jamais de bonne raison de le faire.

Traitez les webhooks comme la source de vérité

La redirection navigateur après un paiement n'est pas une confirmation — l'utilisateur peut fermer l'onglet. C'est le webhook qui vous indique réellement qu'un paiement a abouti. Construisez autour de lui :

• Vérifiez la signature de chaque webhook pour qu'il soit impossible de forger un événement « paiement réussi ».
• Rendez vos handlers idempotents : les prestataires renvoient les événements, le même événement peut donc arriver plusieurs fois. Indexez sur l'ID de l'événement et ignorez les doublons.
• Retournez un 2xx rapide et effectuez le travail lent de manière asynchrone, sinon le prestataire retentera et les doublons s'accumuleront.

Exécuter des commandes depuis la redirection plutôt que depuis le webhook est la cause la plus fréquente de commandes perdues ou exécutées en double.

Gérez les cas limites financiers

Les paiements réels sont plus complexes qu'un simple « paiement réussi » :

• Paiements échoués et nouvelles tentatives : affichez des messages d'erreur clairs et permettez à l'utilisateur d'essayer avec un autre moyen de paiement.
• Remboursements et remboursements partiels : modélisez-les dès le début, pas comme une réflexion après coup.
• Litiges et chargebacks : écoutez ces événements webhook et conservez les justificatifs pour pouvoir répondre.
• Devises et montants : stockez les sommes en unités entières mineures (centimes), jamais en nombres flottants.

Concevez votre flux pour l'authentification forte

Des réglementations comme la SCA en Europe imposent une authentification renforcée sur de nombreux paiements. Les SDK modernes gèrent le 3-D Secure pour vous, mais uniquement si vous utilisez correctement le flux payment-intent. Testez que l'étape de vérification fonctionne bien — un paiement qui échoue silencieusement la SCA ressemble à un checkout cassé pour le client.

Testez avec les outils fournis, pas avec de vraies cartes

Utilisez les numéros de carte de test du prestataire pour simuler un succès, un refus, des fonds insuffisants et un litige. Déclenchez des webhooks de test avec leur CLI. Confirmez que votre idempotence tient réellement en envoyant deux fois le même événement. Ne découvrez pas ces scénarios en production.

Avant la mise en production

• Vérification de signature sur tous les webhooks.
• Handlers idempotents, indexés sur l'ID de l'événement.
• Flux de remboursement et de litige implémentés et testés.
• Montants stockés en unités entières mineures.
• Secrets dans la configuration d'environnement, jamais dans le bundle client.

Chez Pykero, nous intégrons Stripe et des processeurs régionaux dans des produits où un cas limite manqué signifie du chiffre d'affaires perdu. Si les paiements figurent dans votre roadmap, parlons-en.