Cartes de test Stripe

Comment utiliser une carte de test Stripe

Trois étapes. Les cartes de test ne s'utilisent qu'avec des clés API de test : rien ici ne peut toucher une vraie carte ni un vrai client.

1. Passez en clés de test. Utilisez vos clés API publiable et secrète de test, ou un environnement de test. N'utilisez jamais de vraies informations de carte : le Contrat d'utilisation du service Stripe interdit de tester en mode production avec de véritables moyens de paiement.
2. Choisissez la carte du résultat voulu. 4242 4242 4242 4242 pour un paiement réussi. Pour exercer votre gestion des erreurs, prenez la carte dont la ligne affiche le decline code voulu, avec n'importe quel CVC à trois chiffres et une date future comme 12/34.
3. Dans le code serveur, passez le PaymentMethod. Stripe recommande d'utiliser un PaymentMethod comme pm_card_visa plutôt qu'un numéro de carte dans les appels API, même en test, pour que votre code reste conforme à la norme PCI en production. La colonne PaymentMethod donne le token de chaque carte qui en a un.

Tester un paiement français : carte FR, Cartes Bancaires et IBAN SEPA

Pour un site qui encaisse en France, trois lignes du tableau comptent plus que 4242 4242 4242 4242, et Stripe les documente à trois endroits différents.

• La carte française, 4000 0025 0000 0003 (pm_card_fr), en tête du groupe « par pays ». Elle simule un paiement réussi avec une carte émise en France : c'est le pays d'émission qui change, et Stripe calcule les frais transfrontaliers selon ce pays — les cartes émises hors des États-Unis peuvent en supporter, même dans les environnements de test. Ce qu'elle ne teste pas, c'est l'authentification : Stripe précise que les cartes de sa section Europe et Moyen-Orient simulent un paiement qui réussit sans authentification, alors que l'authentification forte du client est exigée pour les paiements en ligne dans l'EEE. Pour 3D Secure, prenez le groupe dédié.
• La carte co-badgée Cartes Bancaires/Visa, 4000 0025 0000 1001 (pm_card_visa_cartesBancaires), dans le groupe des marques. Cartes Bancaires est le réseau de cartes local en France, et selon Stripe plus de 95 % de ces cartes portent aussi la marque Visa ou Mastercard. Le règlement (UE) 2015/751 impose aux entreprises de l'EEE de laisser le titulaire choisir la marque de sa carte co-badgée au moment du paiement : c'est ce sélecteur que cette carte sert à tester. Dans un environnement de test, Stripe affiche le sélecteur de réseau sur ses interfaces hébergées même si Cartes Bancaires n'est pas activé, et Checkout prend ce choix en charge par défaut. Stripe publie une seconde carte co-badgée, Cartes Bancaires/Mastercard (5555 5525 0000 1001), que ce tableau ne reprend pas.
• Les IBAN SEPA français, en tête du tableau des moyens de paiement locaux : FR1420041010050500013M02606 pour un prélèvement qui aboutit, FR8420041010050500013M02607 pour un échec, FR5720041010050500013M02608 pour un litige immédiat, FR9720041010050000002222227 pour des fonds insuffisants, et les variantes qui ne se résolvent qu'au bout de trois minutes. Le Payment Element valide ces IBAN et affiche le mandat quand vous les saisissez. Stripe en publie neuf par pays ; le tableau garde les six scénarios principaux.

Deux choses que ces lignes ne montrent pas, et qu'il vaut mieux savoir avant la mise en production. Côté Cartes Bancaires, Stripe relance automatiquement sur Visa ou Mastercard un paiement refusé sur le réseau CB pour une raison technique, et le commerçant ne peut pas contester un litige Cartes Bancaires — dont les frais sont de 0 EUR. Côté SEPA, un débit de test se résout en quelques minutes ; en production, Stripe recommande d'attendre au moins six jours ouvrables avant de le considérer comme réussi, et le client peut le contester sans justification pendant huit semaines, jusqu'à treize mois si le débit n'était pas autorisé.

Quelle carte déclenche quel échec — et ce que votre webhook va recevoir

Bien gérer un paiement échoué, c'est tenir trois choses en tête à la fois : le error.code que lève votre appel API, le decline_code que l'émetteur y a joint, et l'événement qui arrivera plus tard sur votre point de terminaison webhook. Stripe les documente sur trois pages différentes, si bien que la plupart des intégrations sont écrites d'après l'une d'elles et surprises par les deux autres. Voici la même information, une ligne par résultat.

Deux habitudes découlent de cette lecture en un seul tableau. D'abord, card_declined n'est pas un motif, c'est une catégorie : le motif est dans decline_code. Des huit refus du haut du tableau, cinq en portent un ; les trois autres renvoient un error.code différent. Un gestionnaire d'erreurs qui ne regarde que error.code confond fonds insuffisants et carte volée. Or Stripe demande de ne pas dévoiler au client un refus pour carte perdue ou volée et de le présenter comme un generic_decline, alors que le client à court de fonds peut, lui, agir : ce sont deux messages différents.

Ensuite, certains résultats n'apparaissent jamais dans la réponse. Un paiement mis en examen, un litige ouvert trois semaines plus tard, un remboursement asynchrone qui passe de réussi à échoué : rien de cela n'est visible au moment de l'appel API. Ces résultats arrivent sous forme d'événements, ou n'arrivent pas du tout parce que le point de terminaison n'a jamais été écrit. C'est ce mode d'échec qu'il faut tester exprès : bloquez la carte, puis regardez ce que votre système a fait de l'événement.

Deux notes que le tableau ne peut pas contenir. Stripe ignore les vérifications du CVC et du code postal si vous n'envoyez pas ces champs : les cartes qui simulent un échec de vérification réussissent discrètement tant que votre formulaire ne les collecte pas. Et pour un paiement bloqué par Radar, Stripe documente generic_decline, dont la définition couvre le cas où « Stripe Radar ou Adaptive Acceptance a bloqué le paiement » — le client n'a pas à apprendre qu'il a été jugé suspect.

Tester 3D Secure

La réglementation sur l'authentification forte du client exige 3D Secure pour les paiements en ligne au sein de l'Espace économique européen, et c'est là qu'une intégration qui marche tombe le plus souvent — parce que le chemin heureux ne le voit jamais. Un paiement qui demande une authentification n'échoue pas et ne réussit pas : le PaymentIntent revient en requires_action, et votre front-end doit passer la main à Stripe.js pour que le client réussisse le challenge.

Neuf cartes du tableau parcourent les branches, et la distinction qui fait gagner le plus de temps est requis contre pris en charge :

• 4000 0000 0000 3220 — l'authentification est requise et réussit. C'est la carte sur laquelle construire : vous saurez si votre client appelle vraiment l'étape de confirmation ou traite discrètement requires_action comme un échec.
• 4000 0000 0000 3055 — 3D Secure est pris en charge mais pas demandé par défaut. Utile pour vérifier que vous n'avez pas rendu l'authentification obligatoire par accident.
• 4000 0084 0000 1629 et 4000 0084 0000 1280 — les deux fins ratées : le client s'authentifie et l'émetteur refuse quand même, ou la vérification elle-même échoue. Les deux reviennent en card_declined ; un gestionnaire qui prend un challenge terminé pour un paiement terminé affichera une page de succès pour un paiement qui n'a jamais eu lieu.
• 4000 0025 0000 3155 et 4000 0027 6000 3184 — les cartes enregistrées. La première exige l'authentification pour les paiements hors session tant qu'elle n'est pas configurée pour de futurs paiements ; la seconde l'exige toujours. Si vous comptez débiter vos clients plus tard sans eux, ces deux cartes font la différence entre un renouvellement qui marche et un abonnement mort.

Un piège : seules les cartes de ce groupe testent vraiment 3D Secure. Les autres cartes de test peuvent le déclencher, mais Stripe renvoie attempt_acknowledged et saute les étapes supplémentaires : votre écran de challenge ne s'affiche jamais, et vous en concluez à tort qu'il fonctionne. La carte française et les autres cartes « par pays » européennes, elles, réussissent sans authentification. Enfin, les redirections 3D Secure n'ont pas lieu pour un paiement créé directement dans le Dashboard Stripe : passez par votre propre front-end ou par un appel API.

Cartes de test Stripe par pays

Stripe tient une liste à part de cartes de test par pays : 64 cartes de 58 pays, chacune simulant un paiement réussi avec une carte émise dans ce pays. C'est le dernier groupe du tableau, et sur cette page la ligne France y passe en premier. Les PaymentMethods suivent le code pays — pm_card_fr, pm_card_de, pm_card_jp — à trois exceptions près : la carte mexicaine Carnet et la carte saoudienne n'ont pas de PaymentMethod, et la carte japonaise JCB utilise pm_card_jcb, le même que la carte JCB du groupe des marques. La ligne États-Unis, c'est 4242 4242 4242 4242 elle-même, avec son propre pm_card_us.

Pour simuler l'endroit où se trouve le client plutôt que la provenance de la carte, Stripe documente des adresses e-mail de localisation pour Checkout Sessions, Payment Links et grilles tarifaires : ajoutez +location_XX à la partie locale, par exemple test+location_FR@example.com, et passez-la en customer_email d'une Checkout Session ou en prefilled_email d'un Payment Link. Utile pour vérifier ce qu'un client en France voit s'afficher.

Sous le tableau des cartes figurent les valeurs de test publiées par Stripe pour trois moyens de paiement locaux : les IBAN du prélèvement SEPA pour la France, l'Allemagne et l'Espagne, Konbini pour le Japon et Boleto pour le Brésil. Ils ne se résolvent pas comme une carte. Un prélèvement SEPA attend en processing avant de réussir ou d'échouer, et un bon Konbini ou Boleto attend en requires_action jusqu'à son paiement ou son expiration : chaque ligne donne donc toute la séquence d'événements que recevra votre webhook, et non un seul.

Remboursements, litiges et tout ce qui arrive en retard

En mode production, les remboursements sont asynchrones : un remboursement peut sembler aboutir et échouer ensuite, ou rester pending avant d'aboutir. Presque aucune suite de tests ne le couvre, parce qu'avec une carte de test ordinaire les remboursements aboutissent aussitôt et ne changent plus d'état. Deux cartes rétablissent le vrai comportement : 4000 0000 0000 7726 laisse le remboursement en attente puis le fait réussir, 4000 0000 0000 5126 le déclare réussi puis le fait échouer. Les deux émettent ensuite un événement — exactement le code qu'il vaut mieux avoir écrit avant qu'un client appelle au sujet d'un remboursement jamais reçu.

Les litiges fonctionnent pareil, au ralenti. Le paiement aboutit normalement, puis une rétrofacturation apparaît des jours plus tard, avec charge.dispute.created pour seule notification. 4000 0000 0000 0259 ouvre un litige pour fraude, 4000 0000 0000 2685 un litige pour produit non reçu, et 4000 0000 0000 1976 une demande d'information plutôt qu'une rétrofacturation complète. 4000 0000 0000 5423 produit un avertissement précoce de fraude : le réseau vous prévient qu'un litige arrive probablement, quand il est encore temps de rembourser de vous-même.

Pour simuler l'issue et pas seulement l'événement, répondez au litige avec les chaînes de preuve que Stripe réserve aux tests : winning_evidence clôt le litige comme gagné, losing_evidence le clôt comme perdu, et escalate_inquiry_evidence transforme une demande d'information en rétrofacturation. Rappel pour le marché français : ces scénarios ne représentent pas un litige Cartes Bancaires, que le commerçant ne peut pas contester.

Dernière carte du groupe : 4000 0000 0000 0077 crédite les fonds directement sur votre solde disponible plutôt que sur le solde en attente. Ce n'est pas un test de paiement mais de comptabilité — utile si quelque chose en aval rapproche les virements et que vous ne voulez pas attendre un délai de règlement pour savoir si cela fonctionne.

Télécharger les fixtures en JSON ou en CSV

Un tableau qu'il faut recopier à la main est un tableau qu'on recopiera mal. Les deux boutons de téléchargement en haut de la page donnent les mêmes 119 cartes en fichiers lisibles par machine, générés dans le navigateur à partir des données qui servent à afficher cette page : ce que vous téléchargez ne peut pas s'écarter de ce que vous venez de lire.

Le JSON est un objet avec source, checked, count et un tableau cards. Chaque carte porte un id stable à citer dans le nom d'un test, les chiffres, la marque, le groupe, une description d'une ligne, les règles de CVC et d'expiration, les quatre champs de correspondance — payment_method, error_code, decline_code et webhook_event — et country, le code ISO du pays d'émission pour les cartes du groupe par pays. Les champs sans objet valent null au lieu d'être absents : un parseur n'a jamais à tester une clé manquante.

Le CSV contient les mêmes douze colonnes, avec les guillemets de la RFC 4180 : il s'ouvre dans un tableur et se charge dans pandas sans option de conversion. Les deux fichiers restent en anglais, identiques quelle que soit la langue de la page. Les valeurs des moyens de paiement locaux sont là pour être copiées, pas téléchargées : aucun des deux fichiers ne les contient.

Les deux téléchargements suivent le filtre appliqué. Réduisez le tableau aux refus, cliquez sur Télécharger le JSON, et vous obtenez dix lignes au lieu de 119 — souvent ce qu'attend un test paramétré :

test.each(fixtures.cards.filter(c => c.group === 'decline'))(
  '$id surfaces $decline_code',
  async ({ payment_method, error_code, decline_code }) => { /* … */ },
);

Les fichiers indiquent l'URL source et la date de vérification, parce qu'une liste de cartes sans date est une liste à laquelle on ne peut plus se fier dans six mois. Si Stripe change un numéro, la bonne correction consiste à revérifier la source, pas à garder une copie périmée dans votre dépôt.

Ce que vous construisez vraiment

Personne ne cherche des cartes de test pour le plaisir. Si vous êtes ici, vous branchez un paiement, et le paiement n'est qu'une pièce d'un ensemble : un catalogue, un prix que le client ne peut pas modifier, une session créée quelque part avec un secret, un webhook qui décide si la commande compte comme payée, puis tout ce qui se passe une fois l'argent arrivé.

La pièce qui casse le plus souvent n'est pas la carte, c'est le prix. Un site statique qui garde ses prix dans le HTML et envoie un montant à un point de paiement fait confiance au navigateur pour le chiffre, et le navigateur n'est pas digne de confiance : c'est toute une famille de bugs que les cartes de test ne verront jamais, car un paiement falsifié réussit parfaitement.

Clize s'appuie sur Stripe Checkout pour cette raison et met le prix côté serveur : une boutique hébergée calcule chaque panier d'après le _catalog.json déployé avec le site et ignore le montant annoncé par le client. Si c'est votre problème, le fichier catalogue a un générateur et un validateur (en anglais) ; et s'il vous suffit qu'un client paie un montant, clize pay link --amount 49 renvoie une URL Stripe Checkout en production sans compte Stripe à vous — ce paiement est de l'argent réel, gardez-le bien loin des numéros de cette page.

$ npm i -g @clize/clize && clize login
$ clize pay link --amount 49 --for "facture 1042"