Passerelle de paiement headless et API-first : architecture et intégration en 2026
Le découplage du front et du back-end a profondément changé la façon de concevoir l'encaissement. Une passerelle de paiement headless, pilotée par API, permet de servir n'importe quel point de contact — site web, application mobile, borne, objet connecté — avec un même socle d'orchestration. Ce guide détaille l'architecture, les primitives API des grands PSP, la tokenisation, la 3DS2, les webhooks et l'orchestration multi-prestataires, avec schéma de flux et pseudo-code.
Qu'est-ce qu'une passerelle de paiement headless / API-first ?
Une passerelle de paiement headless désigne une intégration où la logique d'encaissement est exposée exclusivement par des API et des SDK, sans interface graphique imposée. Le terme « headless » (sans tête) signifie que la « tête » — l'interface utilisateur — est découplée du « corps » — le moteur de paiement. Le commerçant construit son propre parcours d'achat, sur la technologie de son choix, et appelle le prestataire de services de paiement (PSP) via des requêtes réseau structurées plutôt que via une page de paiement hébergée toute faite.
L'approche API-first pousse cette logique encore plus loin : l'API n'est pas une surcouche ajoutée après coup sur un produit historique, elle est le produit. Chaque capacité — créer une intention de paiement, tokeniser une carte, déclencher une authentification 3DS2, émettre un remboursement — est une ressource adressable, documentée et versionnée. Cette philosophie s'inscrit dans le mouvement plus large du commerce composable et de l'architecture MACH (Microservices, API-first, Cloud-native, Headless), qui consiste à assembler des briques best-of-breed interchangeables plutôt qu'à déployer une suite monolithique.
Concrètement, dans une architecture headless, votre application single-page (SPA) ou votre application mobile ne « voit » jamais la mécanique interne du PSP. Elle affiche des champs de saisie sécurisés fournis par le prestataire, récupère un jeton ou un identifiant d'intention de paiement, et délègue au back-end la responsabilité d'autoriser et de capturer la transaction. Cette séparation des responsabilités est au cœur de la robustesse, de la sécurité et de la flexibilité du modèle.
Pourquoi passer au headless : omnicanal, performance et flexibilité
Le modèle monolithique — une plateforme e-commerce qui gère à la fois le catalogue, le panier, le rendu HTML et le paiement — reste parfaitement valable pour un marchand mono-canal. Mais quatre forces poussent les équipes techniques vers le headless.
L'omnicanal et le multi-front. Un même marchand peut aujourd'hui vendre via un site web, une application iOS et Android, une marketplace, une borne en magasin, un chatbot, voire un objet connecté. Dupliquer la logique de paiement dans chacun de ces fronts serait ingérable. Avec une passerelle de paiement headless, le socle d'encaissement est mutualisé : chaque front consomme la même API, seul l'affichage change. C'est la promesse du « write once, pay everywhere ».
La performance. Les parcours de paiement hébergés (redirection vers une page du PSP) ajoutent des allers-retours et sortent l'utilisateur de votre domaine, ce qui casse la perception de continuité. Une SPA qui intègre les champs du PSP en place, sans rechargement, offre un parcours plus rapide et mieux maîtrisé. Chaque centaine de millisecondes compte : au-delà de l'image de marque, la fluidité du tunnel influence directement le taux de conversion.
La flexibilité produit. Découpler le front du paiement permet d'itérer sur le design du checkout — A/B testing, parcours en une page, express checkout, wallets — sans toucher au moteur. Les équipes produit et paiement travaillent en parallèle. On peut aussi personnaliser le parcours par segment, par pays ou par appareil sans réécrire l'intégration PSP.
L'interchangeabilité des briques. Dans une pile composable, le CMS, le moteur de recherche, le panier et le paiement sont des services distincts reliés par API. Remplacer un PSP, en ajouter un second, ou brancher une couche d'orchestration devient une opération circonscrite plutôt qu'une refonte. C'est précisément ce que recherche une organisation qui veut éviter le verrouillage fournisseur (vendor lock-in).
| Critère | Architecture monolithique | Architecture headless / API-first |
|---|---|---|
| Couplage front/back | Fort : le rendu et la logique de paiement sont liés | Faible : front et moteur de paiement communiquent par API |
| Multi-front (web, mobile, retail) | Difficile, souvent dupliqué | Natif : un seul socle, plusieurs consommateurs |
| Personnalisation du checkout | Limitée par le thème de la plateforme | Totale, maîtrisée par l'équipe produit |
| Multi-PSP / orchestration | Rare, via plugins spécifiques | Possible via une couche d'abstraction |
| Coût et complexité initiale | Faible (plugin prêt à l'emploi) | Élevé (développement sur-mesure) |
| Time-to-market d'une évolution | Dépend de l'éditeur de la plateforme | Maîtrisé par l'équipe technique |
| Compétences requises | Configuration, un peu de PHP/thème | Développement back-end, DevOps, sécurité |
À retenir : le headless n'est pas intrinsèquement supérieur. Il est supérieur pour qui a plusieurs fronts, des besoins de personnalisation forts ou une stratégie multi-PSP. Pour une boutique mono-canal standard, un bon plugin reste le choix le plus rationnel.
L'architecture type : SPA/mobile ↔ back-end ↔ PSP
L'architecture d'une passerelle de paiement headless repose sur trois couches aux responsabilités strictement séparées. Comprendre où s'arrête chacune est la clé d'une intégration sécurisée.
La couche front (SPA ou application mobile). C'est l'interface vue par l'acheteur. Elle n'a qu'une mission côté paiement : afficher les champs sécurisés fournis par le PSP et transmettre au PSP, directement et sans passer par vos serveurs, les données sensibles. Pour cela, le front utilise une clé publique (publishable key) qui ne permet aucune opération dangereuse. Le front ne connaît jamais la clé secrète, ne manipule jamais un numéro de carte en clair et ne décide jamais seul qu'un paiement a réussi.
La couche back-end. C'est le cœur de la logique. Elle détient la clé secrète du PSP, crée les intentions de paiement, applique les règles métier (montant, devise, exemptions 3DS2, choix du PSP), déclenche la capture et traite les webhooks. Elle est la seule à pouvoir déplacer de l'argent. Toute décision d'état de commande découle d'elle, jamais du front.
La couche PSP. Le prestataire (Stripe, Adyen, Mollie, et leurs acquéreurs) exécute l'autorisation auprès des réseaux cartes, orchestre la 3DS2 avec la banque émettrice, stocke les cartes tokenisées dans son coffre-fort (vault) et émet les webhooks. Il héberge aussi les champs sécurisés que le front affiche.
Le flux nominal d'un paiement par carte dans cette architecture suit une séquence précise. Le point essentiel : les données de carte vont du navigateur de l'acheteur directement au PSP, en court-circuitant vos serveurs, tandis que votre back-end ne manipule que des identifiants opaques.
Acheteur (navigateur / app) Back-end marchand PSP (Stripe/Adyen/Mollie)
│ │ │
│ 1. valide le panier │ │
│────────────────────────────────▶│ │
│ │ 2. crée l'intention │
│ │ (montant, devise) │
│ │───────────────────────────▶│
│ │ 3. client_secret / token │
│ │◀───────────────────────────│
│ 4. client_secret │ │
│◀────────────────────────────────│ │
│ │
│ 5. saisie carte dans les champs hébergés + confirmation │
│─────────────────────────────────────────────────────────────▶│
│ 6. éventuel challenge 3DS2 (iframe / redirect) │
│◀─────────────────────────────────────────────────────────────│
│ │
│ │ 7. webhook : succès/échec │
│ │◀───────────────────────────│
│ │ 8. valide la commande │
│ 9. confirmation affichée │ (source de vérité) │
│◀────────────────────────────────│ │Ce découplage impose une discipline : le front ne doit jamais être cru sur parole. L'étape 9 (affichage de la confirmation) est optimiste ; c'est l'étape 7-8 (le webhook traité côté serveur) qui fait foi. Nous y revenons en détail plus bas.
Les primitives API par PSP : PaymentIntents, Sessions, orders
Chaque grand prestataire expose une primitive centrale qui matérialise « l'intention d'encaisser un montant » et porte le cycle de vie de la transaction. Les noms diffèrent, la philosophie converge.
Stripe — PaymentIntent. Le PaymentIntent est l'objet pivot. Créé côté serveur avec un montant et une devise, il renvoie un client_secret que le front utilise pour confirmer le paiement via Stripe.js ou le SDK mobile. L'objet transite par des statuts (requires_payment_method, requires_confirmation, requires_action pour la 3DS2, processing, succeeded). Stripe gère automatiquement la logique d'authentification et expose les Payment Element pour afficher des dizaines de moyens de paiement avec un seul composant.
Adyen — /sessions et /payments. Adyen propose deux approches. L'API /sessions (Advanced flow simplifié) crée une session côté serveur ; le composant web Adyen (Drop-in ou Components) prend le relais pour tout le cycle, y compris la 3DS2. L'API /payments et /payments/details offre un contrôle plus granulaire, utile pour orchestrer manuellement les étapes d'authentification. Adyen renvoie des codes de résultat (Authorised, Refused, RedirectShopper, ChallengeShopper) qui dictent l'action suivante.
Mollie — orders et payments. Mollie distingue l'API Payments (encaissement simple) de l'API Orders (recommandée pour l'e-commerce, car elle porte les lignes de commande, nécessaires aux paiements fractionnés type Klarna et à la gestion des remboursements partiels). La confirmation passe le plus souvent par une redirection vers une page hébergée Mollie, mais les Mollie Components permettent une intégration de champs en place pour les cartes.
| Brique | Stripe | Adyen | Mollie |
|---|---|---|---|
| Primitive centrale | PaymentIntent | Session / Payment | Payment / Order |
| Champs hébergés | Elements / Payment Element | Components / Drop-in | Mollie Components |
| Jeton front | client_secret | sessionData / paymentData | redirect ou token Components |
| Gestion 3DS2 | handleNextAction | handleAction | géré via redirect / Components |
| Coffre-fort de cartes | Customer + PaymentMethod | Stored Payment Methods (tokens) | Customer + mandates |
| Webhook de succès | payment_intent.succeeded | AUTHORISATION | statut interrogé sur /payments/{id} |
| Abonnements natifs | Billing (Subscriptions) | Recurring / Tokenization | Subscriptions |
Pour approfondir le détail des requêtes, des clés et de la gestion d'erreur, consultez notre guide dédié à l'intégration d'une API de paiement, qui décrit pas à pas la création d'une transaction côté serveur et l'enchaînement des appels.
Tokenisation et PCI-DSS : réduire le périmètre avec les champs hébergés
La sécurité des données de carte est la contrainte structurante d'une passerelle de paiement headless. La norme PCI-DSS (Payment Card Industry Data Security Standard) classe les marchands selon la façon dont ils manipulent les données de carte, et le niveau d'exigence varie du simple au très lourd.
Le principe directeur est de ne jamais faire transiter le numéro de carte (PAN), la date d'expiration ni le cryptogramme par vos serveurs ou votre code JavaScript applicatif. Pour cela, les PSP fournissent des champs hébergés : des iframes isolées, servies depuis le domaine du prestataire, intégrées visuellement dans votre page mais hors de portée de votre code. L'acheteur saisit sa carte dans ces champs ; les données partent directement chez le PSP, qui renvoie un jeton (token) — une référence opaque inutilisable par un tiers.
- Stripe Elements : composants d'interface (Card Element, Payment Element) qui tokenisent la carte côté navigateur. Les données ne touchent jamais votre serveur.
- Adyen Components / Drop-in : briques prêtes à l'emploi qui gèrent la saisie, le chiffrement côté client (CSE) et l'affichage des moyens de paiement locaux.
- Mollie Components : champs isolés pour la carte, avec génération d'un token transmis au serveur à la place du PAN.
Grâce à cette mécanique, un marchand qui utilise exclusivement des champs hébergés reste généralement éligible au SAQ A (Self-Assessment Questionnaire A), le questionnaire d'auto-évaluation le plus léger — une poignée de contrôles, contre plus de 300 pour le SAQ D exigé dès que vous touchez au PAN en clair. C'est un argument décisif : une architecture headless bien conçue réduit le périmètre PCI-DSS au lieu de l'étendre.
La tokenisation ne sert pas qu'à la conformité. Un token enregistré dans le coffre-fort du PSP (Stripe PaymentMethod, Adyen stored payment method, mandat Mollie) permet de réencaisser un client sans lui redemander sa carte : c'est la base des abonnements, du one-click et du paiement en magasin rattaché à un compte. Nous détaillons les mécanismes et les bonnes pratiques dans notre article sur la tokenisation du paiement.
La 3DS2 en contexte headless
L'authentification forte (SCA) imposée par la DSP2 ajoute une étape potentielle au flux : le challenge 3DS2. Dans une architecture headless, la difficulté est de gérer cette étape sans casser le parcours de la SPA ou de l'application mobile.
Le mécanisme est le suivant. Quand le back-end confirme l'intention de paiement, le PSP peut répondre que la transaction nécessite une action (requires_action chez Stripe, ChallengeShopper ou RedirectShopper chez Adyen). Le front doit alors exécuter cette action : le SDK affiche une iframe ou redirige vers la page d'authentification de la banque émettrice (notification push, biométrie, OTP SMS). Une fois le challenge résolu, le front signale la fin de l'action et le back-end vérifie le statut définitif.
Les SDK modernes masquent la complexité. stripe.handleNextAction(), checkout.handleAction() chez Adyen, ou le composant Mollie prennent en charge l'affichage du challenge, y compris en environnement natif iOS/Android où une WebView encapsule l'authentification. Le développeur n'a pas à réimplémenter le protocole EMV 3DS.
Point de vigilance : en contexte mobile et SPA, un challenge 3DS2 peut interrompre la session (redirection externe, bascule d'application bancaire). Ne considérez jamais un retour de challenge comme une preuve de succès : c'est le webhook côté serveur qui confirme l'autorisation définitive.
Pour maîtriser les exemptions, le liability shift et l'impact sur la conversion, reportez-vous à notre guide complet sur la 3DS2 et l'authentification forte, qui détaille les cas où l'on peut passer en frictionless.
Les webhooks comme source de vérité et l'idempotence
Dans une passerelle de paiement headless, la règle d'or est : le front ne décide pas de l'état d'un paiement, le webhook si. Un webhook est une notification HTTP envoyée par le PSP à une URL de votre back-end dès qu'un événement survient (payment_intent.succeeded, payment_intent.payment_failed, AUTHORISATION, charge.refunded...).
Pourquoi ne pas se contenter de la réponse HTTP reçue par le front ? Parce que de nombreux scénarios rompent le lien direct :
- Le moyen de paiement est asynchrone : un virement, un prélèvement SEPA ou un paiement type iDEAL/Bancontact peut se confirmer plusieurs minutes, voire plusieurs jours, après la fin de la session.
- L'acheteur ferme l'onglet ou perd le réseau juste après avoir payé mais avant que le front reçoive la confirmation.
- Un challenge 3DS2 redirige vers une application bancaire et l'acheteur ne revient jamais sur votre page, bien que le paiement ait réussi.
Dans tous ces cas, le webhook est le seul signal fiable. Il faut donc traiter la validation de commande, l'envoi de l'e-mail de confirmation et la préparation de l'expédition à partir de l'événement webhook, pas à partir de la réponse front.
Deux exigences techniques encadrent cette fiabilité. D'abord la vérification de signature : chaque PSP signe ses webhooks (en-tête Stripe-Signature, HMAC Adyen, etc.) pour garantir qu'ils proviennent bien de lui et n'ont pas été falsifiés. Ensuite l'idempotence : les PSP garantissent une livraison « au moins une fois » et réémettent un webhook s'ils ne reçoivent pas un 200 rapide. Votre endpoint doit donc résister aux doublons — en stockant l'identifiant d'événement déjà traité et en ignorant les rejeux.
L'idempotence vaut aussi dans l'autre sens, lors de vos appels sortants. Les API de paiement acceptent une clé d'idempotence (Idempotency-Key chez Stripe) : si une requête de création de paiement part deux fois à cause d'un timeout réseau, la clé garantit qu'une seule transaction est créée. C'est indispensable pour ne pas débiter deux fois un client. Ces mécanismes, leur configuration et les files de retry sont approfondis dans notre article sur la façon de fiabiliser les webhooks de paiement.
Schéma de flux et pseudo-code : création puis confirmation
Voici un pseudo-code illustrant les deux moments clés d'un paiement headless par carte : la création de l'intention côté serveur, puis la confirmation côté client avec gestion de la 3DS2 et validation finale par webhook.
1. Back-end — création de l'intention de paiement (avec idempotence) :
// Serveur — jamais exposé au navigateur
POST /api/payments/create
function createPayment(cart, user) {
// Recalcul du montant côté serveur : ne jamais faire confiance au front
const amount = computeAmountFromCart(cart); // en centimes
const currency = "EUR";
const intent = psp.paymentIntents.create(
{
amount: amount,
currency: currency,
customer: user.pspCustomerId, // pour le vaulting
automatic_payment_methods: { enabled: true },
metadata: { orderId: cart.orderId }
},
{ idempotencyKey: "order-" + cart.orderId } // anti-doublon
);
// On ne renvoie QUE le secret client, jamais la clé secrète
return { clientSecret: intent.client_secret };
}2. Front — confirmation et gestion du challenge 3DS2 :
// Navigateur / app — clé PUBLIQUE uniquement
async function confirmPayment(clientSecret) {
const result = await psp.confirmPayment({
clientSecret,
elements, // champs hébergés (carte jamais lue par notre code)
confirmParams: { return_url: "https://boutique.fr/retour" }
});
if (result.error) {
showError(result.error.message); // refus, carte invalide...
} else if (result.status === "requires_action") {
// Le SDK gère le challenge 3DS2 (iframe / redirect banque)
await psp.handleNextAction({ clientSecret });
}
// IMPORTANT : on n'affiche qu'un "paiement en cours".
// La validation réelle viendra du webhook serveur.
showPending();
}3. Back-end — webhook, source de vérité :
POST /api/webhooks/psp
function handleWebhook(request) {
// 1. Vérifier la signature — rejeter si invalide
const event = psp.verifySignature(request.body, request.headers, WEBHOOK_SECRET);
// 2. Idempotence : a-t-on déjà traité cet événement ?
if (alreadyProcessed(event.id)) return respond(200);
// 3. Agir selon le type d'événement
if (event.type === "payment_intent.succeeded") {
const orderId = event.data.object.metadata.orderId;
markOrderPaid(orderId); // valide la commande
sendConfirmationEmail(orderId);
} else if (event.type === "payment_intent.payment_failed") {
markOrderFailed(event.data.object.metadata.orderId);
}
// 4. Mémoriser l'événement et répondre vite
storeProcessed(event.id);
return respond(200);
}Ces trois blocs résument l'intégralité de la discipline headless : le montant est recalculé côté serveur, la carte ne touche jamais votre code, l'idempotence protège de l'avant comme de l'arrière, et la décision d'état vient du webhook.
Multi-PSP et orchestration de paiement
L'un des bénéfices les plus stratégiques de l'approche API-first est la possibilité de brancher plusieurs PSP derrière une interface unique. Cette couche d'orchestration de paiement (payment orchestration) abstrait les prestataires et apporte plusieurs capacités.
- Routage intelligent (smart routing) : diriger chaque transaction vers le PSP le plus pertinent selon le pays de la carte, la devise, le moyen de paiement ou le coût d'acquisition. Un paiement local peut ainsi être routé vers l'acquéreur qui offre le meilleur taux d'autorisation dans ce pays.
- Repli automatique (fallback / cascading) : si un PSP refuse ou tombe en panne, la transaction est automatiquement rejouée auprès d'un second prestataire. Ce mécanisme récupère une part non négligeable des échecs techniques et améliore le taux d'autorisation global.
- Résilience et indépendance : ne plus dépendre d'un seul fournisseur réduit le risque opérationnel et la pression contractuelle.
- Vue unifiée : réconcilier les transactions de plusieurs PSP dans un reporting unique.
Des acteurs spécialisés — Primer, Gr4vy, Spreedly, ou encore les couches d'orchestration proposées par certains PSP — fournissent cette abstraction en SaaS. Il est aussi possible de la construire soi-même : on définit alors une interface interne (créer, confirmer, rembourser) que chaque adaptateur PSP implémente. Cet effort d'ingénierie n'a de sens qu'à partir d'un volume et d'une complexité géographique significatifs ; en deçà, un PSP unique bien choisi reste plus simple et plus économique.
Compromis à mesurer : l'orchestration multi-PSP ajoute une couche à maintenir, multiplie les webhooks à réconcilier et complique la tokenisation (un token Stripe n'est pas utilisable chez Adyen, sauf network token). Elle se justifie par le gain sur le taux d'autorisation et la résilience, pas par principe.
Abonnements, récurrence et vaulting
Les modèles par abonnement reposent entièrement sur la capacité à réencaisser un client sans sa présence. C'est le rôle du vaulting : stocker, chez le PSP, une référence réutilisable de la carte (le token), associée à un objet client.
Lors du premier paiement, l'acheteur est présent et peut passer une authentification 3DS2 : on en profite pour enregistrer le moyen de paiement avec le bon indicateur de mandat (customer-initiated transaction). Les paiements suivants, initiés par le marchand (merchant-initiated transactions, MIT), s'appuient sur ce token et bénéficient d'exemptions SCA pour les montants récurrents fixes. Il est crucial de qualifier correctement chaque transaction (CIT vs MIT, récurrence fixe ou variable) : une erreur de typage provoque des refus bancaires évitables.
Les PSP proposent des moteurs d'abonnement clés en main — Stripe Billing, les flux Recurring d'Adyen, Mollie Subscriptions — qui gèrent les cycles de facturation, les tentatives de relance en cas d'échec (dunning) et les mises à jour automatiques de carte (account updater, qui récupère les nouveaux numéros après expiration ou réémission). Dans une architecture headless, ces moteurs sont pilotés par API : votre back-end crée l'abonnement, le PSP déclenche les prélèvements et émet un webhook à chaque échéance, que votre système traite comme source de vérité.
Intégration avec un CMS headless et le commerce composable
La passerelle de paiement headless ne vit pas seule : elle s'insère dans une pile composable où le contenu, le catalogue, le panier et l'encaissement sont des services distincts. Un CMS headless (Contentful, Strapi, Sanity...) gère le contenu éditorial et produit via API, un moteur de commerce (commercetools, Medusa, Saleor...) gère le panier et les commandes, et le PSP gère le paiement. Le front — souvent construit avec Next.js, Nuxt ou une application mobile — assemble le tout.
Le point d'articulation est le back-end for front-end (BFF), qui orchestre les appels : il récupère le panier du moteur de commerce, calcule le montant, crée l'intention de paiement auprès du PSP et renvoie au front juste ce qu'il faut. La séparation des responsabilités est la même qu'au niveau paiement : chaque service expose une API, le front ne manipule que des références.
Cette composition apporte une liberté réelle — remplacer le CMS sans toucher au paiement, changer de PSP sans refondre le catalogue — mais elle déplace la complexité vers l'intégration et la cohérence des données. La réconciliation entre l'état d'une commande dans le moteur de commerce et l'état du paiement chez le PSP (via webhooks) devient un enjeu central. Nous détaillons les patterns concrets, les webhooks croisés et les pièges de synchronisation dans notre guide sur l'intégration d'une passerelle à un CMS headless.
En synthèse, une passerelle de paiement headless n'est pas qu'une question d'outils : c'est une architecture de responsabilités. Front qui affiche et tokenise, back-end qui décide et orchestre, PSP qui exécute et notifie. Tant que cette frontière est respectée, le modèle offre une flexibilité et une sécurité que le monolithe ne peut égaler ; dès qu'elle est franchie — une carte qui transite par vos serveurs, un état décidé par le front — les bénéfices s'effondrent et le risque explose.
Questions fréquentes
Qu'est-ce qu'une passerelle de paiement headless ?
C'est une approche d'intégration où la logique de paiement est exposée uniquement via des API et des SDK, sans interface imposée. Le marchand garde la maîtrise totale de son front (SPA React, application mobile, borne, objet connecté) et appelle le PSP via des primitives API comme les PaymentIntents de Stripe ou les Sessions d'Adyen. Le back-end orchestre l'autorisation, la 3DS2 et la capture, pendant que le front ne manipule que des champs hébergés pour rester hors périmètre PCI-DSS.
Headless ou plugin e-commerce classique : que choisir ?
Un plugin sur une plateforme monolithique (PrestaShop, WooCommerce, Magento) suffit si vous avez un seul front web standard et peu de besoins sur-mesure. L'approche headless devient pertinente dès que vous devez servir plusieurs points de contact, itérer vite sur le parcours de paiement, ou brancher plusieurs PSP derrière une couche d'orchestration. Le coût de développement est plus élevé, mais la flexibilité et la performance sont nettement supérieures.
Une intégration headless augmente-t-elle le périmètre PCI-DSS ?
Non, au contraire, si elle est bien conçue. En utilisant les champs hébergés (Stripe Elements, Adyen Components, Mollie Components) ou un Drop-in, les données de carte ne transitent jamais par vos serveurs ni par votre JavaScript applicatif. Vous restez généralement éligible au SAQ A, le questionnaire d'auto-évaluation le plus léger. C'est seulement si vous collectez vous-même le PAN en clair que vous basculez vers le SAQ D, bien plus lourd.
Comment gérer la 3DS2 dans une architecture headless ?
Le back-end crée l'intention et déclenche l'authentification ; le PSP renvoie éventuellement une action (challenge) que le SDK front exécute en affichant la fenêtre d'authentification de la banque. Une fois le challenge résolu, le front confirme et le back-end vérifie le statut final via webhook. Les SDK Stripe (handleNextAction), Adyen (handleAction) et Mollie gèrent automatiquement le redirect ou l'iframe, y compris en application mobile.
Pourquoi les webhooks sont-ils la source de vérité en API-first ?
Parce que le résultat d'un paiement peut arriver après la fin de la session : paiement asynchrone (virement, SEPA), timeout réseau, challenge 3DS2 abandonné puis repris, onglet fermé. Se fier à la seule réponse HTTP du front est dangereux. Le webhook envoyé par le PSP est l'événement qui doit déclencher la validation de commande, idéalement traité de manière idempotente pour résister aux doublons et aux rejeux.
Peut-on brancher plusieurs PSP derrière une même passerelle headless ?
Oui, c'est l'un des principaux atouts de l'API-first. Une couche d'orchestration abstrait les PSP derrière une interface unique, route chaque transaction vers le prestataire le plus pertinent (pays, devise, coût) et permet le repli automatique si un PSP échoue. Des acteurs comme Primer, Gr4vy ou Spreedly fournissent cette couche, ou vous pouvez la construire vous-même au prix d'un effort d'ingénierie conséquent.
Articles liés :