Diagramme d'intégration d'une passerelle de paiement : autorisation, 3-D Secure, capture et webhooks

Sur la plupart des diagrammes d'architecture, un paiement est une simple flèche de la boutique vers « Stripe » ou « Adyen ». En production, c'est une chaîne d'acteurs et deux chronologies : ce qui se passe pendant que le client attend sur la page de paiement, et ce qui arrive quelques minutes ou quelques jours plus tard par webhook. La plupart des bugs de paiement vivent dans l'écart entre les deux.

Ce guide dessine un paiement par carte du point de vue des ingénieurs du marchand : les acteurs, le chemin nominal, pourquoi le résultat affiché dans le navigateur ne fait pas foi, ce qui se passe après l'autorisation, et un diagramme qui montre où l'argent et l'état de la commande changent. Il est indépendant des fournisseurs ; Stripe et Adyen n'apparaissent qu'à titre d'exemples de la façon dont les prestataires de services de paiement documentent les détails.

Les acteurs

Le chemin nominal

1. Le client sélectionne Payer. Le frontend demande à votre backend de lancer le paiement d'une commande.
2. Le backend crée un paiement chez le PSP avec le montant, la devise, l'identifiant de commande et une clé d'idempotence, puis transmet au frontend le jeton client du PSP.
3. Le frontend recueille les données de carte dans les champs du PSP, en général des iframes ou un SDK : le numéro de carte va directement du navigateur au PSP et ne touche jamais vos serveurs.
4. L'émetteur décide du 3-D Secure. EMVCo décrit deux parcours : dans le parcours sans friction, l'émetteur accepte sur la base d'une analyse de risque sans rien demander au client ; dans le parcours avec challenge, le client confirme, par exemple avec un code à usage unique ou son application bancaire. Dans certaines régions, c'est ainsi que l'on satisfait l'authentification forte du client.
5. Le PSP envoie l'autorisation à l'émetteur via l'acquéreur et le réseau de cartes ; l'émetteur accepte et bloque les fonds.
6. Le frontend affiche le résultat. Afficher « Merci » ne pose pas de problème, mais ce n'est pas le moment d'expédier.
7. Le PSP envoie un webhook indiquant que le paiement a été autorisé. Votre backend le vérifie et met à jour la commande.
8. Le backend capture le paiement à l'expédition de la commande, ou immédiatement pour les biens numériques.
9. Le PSP effectue les versements, par lots et frais déduits, et une tâche de rapprochement associe les versements aux commandes.

Les champs de carte comptent pour la conformité. Quand un site e-commerce se contente d'intégrer le formulaire de paiement d'un PSP et ne stocke, ne traite ni ne transmet lui-même aucune donnée de carte, il peut relever du PCI DSS SAQ A au lieu du SAQ A-EP, bien plus long. Avec PCI DSS v4.0.1, cela impose aussi de protéger la page contre les scripts malveillants, comme l'explique le PCI Security Standards Council. Confirmez le bon questionnaire avec votre acquéreur.

Pourquoi le navigateur ne fait pas foi

Le client peut fermer l'onglet pendant le 3-D Secure, perdre la connexion après l'accord de l'émetteur ou actualiser la page au mauvais moment. Si l'état de vos commandes dépend du retour du navigateur, certaines commandes payées resteront impayées et certaines commandes échouées sembleront payées. Ce sont les webhooks du PSP, ou son API, qui font foi. Traitez-les comme n'importe quel autre flux de messages :

• Vérifiez la signature. Les PSP signent leurs requêtes de webhook, par exemple Stripe dans un en-tête Stripe-Signature et Adyen avec des signatures HMAC. Rejetez tout ce qui ne se vérifie pas.
• Répondez vite, traitez plus tard. Le guide des webhooks de Stripe demande une réponse 2xx avant toute logique complexe. Placez l'événement vérifié dans une file et répondez.
• Attendez-vous aux doublons. Un endpoint peut recevoir le même événement plusieurs fois. Enregistrez les identifiants d'événements traités et ignorez les répétitions.
• Ne comptez pas sur l'ordre. Stripe indique ne pas garantir la livraison dans l'ordre de création des événements. Quand un événement ne correspond pas à l'état actuel, récupérez le paiement via l'API du PSP.
• Attendez-vous aux nouvelles tentatives. En mode live, Stripe retente les livraisons échouées pendant trois jours au maximum, avec un backoff exponentiel : un endpoint lent recevra donc le même événement plus tard.

La même discipline s'applique dans l'autre sens. Envoyez une clé d'idempotence avec chaque requête qui crée ou modifie un paiement, et réutilisez-la lorsque vous réessayez après un timeout, pour qu'une nouvelle tentative ne puisse pas débiter deux fois. Les clés ne vivent pas éternellement : Stripe peut les supprimer après 24 heures, et Adyen les conserve de 7 à 14 jours.

Après l'autorisation : capture, remboursements, rétrofacturations et versements

• L'autorisation bloque, la capture déplace l'argent. Une autorisation expire si vous ne la capturez pas. Pour les paiements par carte en ligne, le délai est généralement d'environ une semaine, et Stripe le détaille par marque de carte et selon qui a initié le paiement. Capturez avant l'échéance, sinon le blocage est levé.
• Une capture peut encore échouer. Adyen documente de rares cas où le réseau de cartes rejette une capture après que le PSP l'a acceptée ; vos états de commande ont donc besoin d'un chemin pour ce cas.
• Les remboursements sont de nouvelles opérations sur un paiement capturé. Ils se terminent de façon asynchrone et arrivent eux aussi par webhook.
• Les rétrofacturations viennent de l'émetteur, parfois des semaines plus tard, quand un porteur conteste un paiement. Certains réseaux commencent par une demande d'information ; répondez-y, sinon elle peut se transformer en rétrofacturation difficile à gagner.
• Les versements exigent un rapprochement. Associez chaque versement aux paiements, remboursements, frais et rétrofacturations qu'il règle, à l'aide des rapports de versement ou de règlement du PSP.

Le diagramme

Comment le lire :

• Les liens pleins sont le paiement lui-même : payer (1), lancer le paiement (2), créer le paiement (3), envoyer les données de carte au PSP depuis ses champs (4), puis 3-D Secure et autorisation entre le PSP et le réseau de cartes (5).
• Les liens en tirets arrivent plus tard : le webhook (6), l'événement vérifié placé dans une file (7) et l'API de paiement qui met à jour la commande (8). La tâche de rapprochement nocturne lit les rapports de versement du PSP et les associe aux commandes.
• Le cadre délimite les systèmes du marchand. Aucune donnée de carte brute n'y entre ; le numéro de carte va des champs du PSP directement au PSP.

Comment dessiner un flux de paiement

• Numérotez les étapes. Un paiement est une séquence ; les numéros rendent l'ordre lisible sans diagramme de séquence séparé.
• Séparez le synchrone de l'asynchrone. Trait plein pour la requête de paiement, tirets pour les webhooks, les files et les traitements par lots.
• Marquez la frontière des données de carte. Montrez quels composants peuvent voir les numéros de carte. Avec des champs hébergés, aucun des vôtres ne devrait les voir.
• Montrez où l'état de la commande change. Un seul composant devrait en être responsable, alimenté par des événements vérifiés, pas par le navigateur.
• Nommez les opérations financières. Autorisation, capture, remboursement et versement sont des événements différents, avec des délais différents ; étiquetez-les.
• Dessinez les cas d'échec qui comptent : un timeout à la création (réessayer avec la même clé d'idempotence), un webhook en double (dédupliquer), un challenge 3-D Secure abandonné (faire expirer la commande), une autorisation expirée (réautoriser ou annuler).

Pour une vue en séquence du même flux, consultez le cas d'usage du diagramme de flux de paiement. Pour le côté événements, voyez le guide du diagramme d'architecture orientée événements, et pour la revue de sécurité, les diagrammes de flux de données pour la modélisation des menaces.

Le construire dans Archboard

1. Connectez-vous avec Google ou GitHub et créez un diagramme.
2. Ajoutez une Personne du pack Modèle C4 pour le client et deux nœuds Système externe du pack Modèle C4 : un pour le prestataire de services de paiement, un pour l'acquéreur, le réseau de cartes et l'émetteur.
3. Ajoutez un Cadre du pack Base pour les systèmes du marchand et placez-y quatre nœuds Conteneur du pack Modèle C4 : l'application web de checkout, l'API de paiement, le gestionnaire de webhooks et la tâche de rapprochement.
4. Ajoutez dans le cadre un Postgres du pack Données pour les commandes et les paiements, et une File d'attente du pack Données pour les événements de paiement.
5. Numérotez les liens dans l'ordre, passez en tirets les liens du webhook, de la file et du rapprochement, et ajoutez un bloc Markdown du pack Base qui explique les styles de trait.

L'exemple utilise 11 nœuds de diagramme et reste dans les limites de l'offre Free.

FAQ

Quelle est la différence entre une passerelle de paiement et un processeur de paiement ? La passerelle est l'interface avec laquelle vos systèmes communiquent : API, champs de carte, webhooks. Le processeur fait circuler la transaction dans les réseaux de cartes. Beaucoup de PSP fournissent les deux, avec une relation d'acquisition.

Puis-je marquer une commande comme payée quand le navigateur dit que le paiement a réussi ? Affichez une confirmation au client, mais ne changez l'état de la commande qu'à partir d'un webhook vérifié ou d'une vérification auprès de l'API du PSP.

Pourquoi autoriser d'abord et capturer ensuite ? Pour ne facturer que ce qui est expédié. Le blocage garantit les fonds ; la capture les déplace au moment où vous livrez. Surveillez l'expiration de l'autorisation.

Dois-je gérer des webhooks qui arrivent dans le désordre ? Oui. Rendez le gestionnaire idempotent, gérez la commande comme une machine à états qui rejette les transitions impossibles, et récupérez le paiement courant auprès du PSP en cas de doute.

Utiliser des champs hébergés me rend-il conforme PCI ? Cela réduit le périmètre, sans le supprimer. Vous remplissez toujours un questionnaire d'auto-évaluation et vous protégez la page de paiement. Demandez à votre acquéreur lequel s'applique.

Commencez gratuitement — un siège, sans carte bancaire.