Choisir votre parcours d’enregistrement
Deux options, selon que l’utilisateur paie aussi en ce moment ou non.Enregistrer un moyen de paiement avec les éléments de paiement
Construisez le formulaire d’enregistrement sur les éléments de paiement enmode: "setup". L’élément ne propose que les moyens pouvant être enregistrés, affiche à l’acheteur le consentement d’utilisation future qu’exige l’enregistrement et vous remet un jeton de confirmation. Vous transformez ce jeton en setup intent depuis votre serveur, et le client_secret du setup intent finalise toute étape encore due par l’acheteur.
Monter le formulaire en mode setup
mode="setup" et la devise avec laquelle le moyen enregistré sera utilisé. Il n’y a pas de montant, donc les limites de montant ne s’appliquent pas. Définissez returnUrl sur une page que vous hébergez en https. Les inscriptions bancaires et certains parcours 3D Secure y ramènent l’acheteur.mode="setup" lorsque l’acheteur ne paie pas.Créer le setup intent sur votre serveur
201 Created avec le setup intent. Celui-ci porte le status, un client_secret pour toute étape encore due par l’acheteur et, une fois succeeded, le moyen enregistré sous payment_method_id. Joignez des metadata pour relier le moyen enregistré à un client de votre système. Elles vous sont renvoyées dans le webhook. Envoyez une Idempotency-Key pour qu’une requête relancée n’enregistre jamais le moyen deux fois.Finaliser toute étape en attente
succeeded a le moyen enregistré. requires_action signifie que l’acheteur doit encore effectuer une étape, comme 3D Secure ou une inscription bancaire. Transmettez le client_secret à handleNextAction, le même appel que celui du parcours de paiement. Il exécute une étape en ligne dans une boîte de dialogue ou envoie l’acheteur vers votre returnUrl. Faites un branchement selon le status qu’il renvoie : succeeded signifie que le moyen est enregistré, processing que la décision est en cours, et toute autre valeur nécessite une nouvelle tentative. Une boîte de dialogue fermée laisse le setup en requires_action sans erreur, et lastPaymentError indique la raison lorsque la tentative échoue. processing signifie que le processeur n’a pas encore tranché : affichez donc un état en attente et laissez le webhook ci-dessous confirmer l’enregistrement. canceled signifie que l’acheteur a abandonné l’étape ou que le fournisseur a refusé le moyen : last_setup_error indique la raison du fournisseur et reste null lorsque l’acheteur est parti. Pour lire l’état depuis votre serveur, récupérez le setup intent et faites un branchement sur le même status, ou interrogez l’endpoint plus léger Retrieve setup status tant qu’une étape est en attente.Gérer la finalisation
setup_intent.succeeded pour récupérer l’ID du moyen de paiement et vos metadata. C’est le seul signal qui survit à un onglet fermé, et le même gestionnaire sert au parcours hébergé ci-dessous. Le setup intent porte également payment_instrument pour l’affichage : un nom, le jeu d’icônes standard et, pour une carte, sa marque, ses quatre derniers chiffres et sa date d’expiration. Vous pouvez afficher le moyen enregistré sans requête supplémentaire. Les webhooks épinglés à une version de l’API antérieure à 2026-09-22-1 transmettent plutôt le moyen enregistré sous payment_method.id.Enregistrer un moyen de paiement avec un checkout hébergé
Créer une configuration de checkout en mode setup
Diriger l'utilisateur vers le checkout
- Intégré
- Redirection
returnUrl avec setup_intent_id dans la chaîne de requête. Confirmez l’enregistrement
à partir du webhook setup_intent.succeeded plutôt qu’à partir de la redirection.Gérer la finalisation
setup_intent.succeeded pour récupérer l’ID du moyen de paiement. Le setup intent porte checkout_configuration_id et les metadata de la configuration, que vous pouvez utiliser pour relier le membre et le moyen de paiement à un client de votre système.redirect_url. C’est le seul signal qui survit à un onglet fermé.Débiter un moyen de paiement enregistré
Obtenir le moyen de paiement
payment_method_id du setup intent de l’étape précédente.Créer un paiement hors session
Gérer les événements de paiement
Enregistrer pendant le checkout
Pour enregistrer un moyen de paiement tout en débitant l’acheteur, construisez le checkout sur les éléments de paiement et transmettezsetupFutureUsage: "off_session" sur le handle Payments. Les éléments affichent à l’acheteur le consentement d’enregistrement et l’inscrivent dans le jeton de confirmation, et le paiement n’enregistre le moyen que lorsque ce consentement est attesté.
La propriété Elements permettant de sélectionner une variante reste nommée plan pour des raisons de compatibilité.
Monter le formulaire avec le consentement d'enregistrement
createConfirmationToken et handleNextAction.Créer le paiement avec le jeton de confirmation
payment_method_id du moyen enregistré arrive dans le webhook payment.succeeded une fois le débit finalisé.Le débiter plus tard
payment_method_id est le moyen payt_ à utiliser dans Débiter un moyen de paiement enregistré. Il reste null lorsque rien n’a été enregistré. Le webhook payment.succeeded porte le même champ, et c’est le chemin qui survit à un onglet fermé.Étapes suivantes
Accepter des paiements
Élément Checkout
Écouter les webhooks
setup_intent.succeeded, payment.succeeded et payment.failed.
