Skip to main content
Utilisez des moyens de paiement enregistrés pour débiter automatiquement vos clients pour des abonnements, des renouvellements ou une facturation à l’usage. Le client enregistre sa carte une seule fois via un parcours Whop hébergé ou intégré, et vous pouvez la débiter à tout moment par la suite.
Associez ce guide aux webhooks : écoutez setup_intent.succeeded pour confirmer l’enregistrement, puis payment.succeeded / payment.failed pour suivre les débits ultérieurs.

Choisir votre parcours d’enregistrement

Deux options, selon que l’utilisateur paie aussi en ce moment ou non. Le reste de cette page couvre le mode setup de bout en bout, puis montre comment débiter ultérieurement un moyen enregistré.

Enregistrer un moyen de paiement avec les éléments de paiement

Construisez le formulaire d’enregistrement sur les éléments de paiement en mode: "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.
1

Monter le formulaire en mode setup

Transmettez 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.
Le jeton porte le consentement affiché par l’élément. Un jeton collecté depuis un formulaire en mode paiement est refusé par le setup intent : montez donc en mode="setup" lorsque l’acheteur ne paie pas.
2

Créer le setup intent sur votre serveur

Créez un setup intent avec le jeton de confirmation. Whop identifie l’acheteur à partir de l’e-mail du jeton et répond 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.
3

Finaliser toute étape en attente

Un setup intent renvoyé avec 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.
4

Gérer la finalisation

Écoutez le webhook 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.
Le moyen de paiement est désormais enregistré et autorisé pour ce membre. Débitez-le en suivant les étapes de Débiter un moyen de paiement enregistré.

Enregistrer un moyen de paiement avec un checkout hébergé

1

Créer une configuration de checkout en mode setup

Créez une configuration de checkout sans variante pour collecter les informations de paiement sans débiter. Ajoutez des métadonnées pour pouvoir relier le membre et le moyen de paiement à un client de votre système.
2

Diriger l'utilisateur vers le checkout

Montez l’élément Checkout ou redirigez l’utilisateur pour qu’il enregistre son moyen de paiement.
Une configuration en mode setup monte le même élément sous forme d’enregistrement de moyen de paiement : rien n’est débité, et le checkout terminé redirige vers 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.
3

Gérer la finalisation

Écoutez le webhook 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.
Confirmez l’enregistrement à partir du webhook plutôt qu’à l’arrivée de l’acheteur sur votre redirect_url. C’est le seul signal qui survit à un onglet fermé.
L’exemple utilise waitUntil de @vercel/functions pour exécuter le gestionnaire après avoir répondu 200. Sur d’autres environnements d’exécution (Bun, Cloudflare Workers, Fastify, Hono), remplacez-le par la primitive de tâche en arrière-plan équivalente de votre framework ou par une file de tâches. Consultez le guide des webhooks pour les équivalents de gestionnaires en Python et Ruby.
Le moyen de paiement est désormais enregistré et autorisé pour ce membre.

Débiter un moyen de paiement enregistré

1

Obtenir le moyen de paiement

Listez les moyens de paiement enregistrés d’un membre, ou utilisez le payment_method_id du setup intent de l’étape précédente.
2

Créer un paiement hors session

Débitez le moyen de paiement sans interaction du client. L’endpoint de création de paiement renvoie immédiatement un objet paiement et traite le débit de manière asynchrone.
Vous pouvez aussi envoyer des line_items pour combiner des variantes existantes avec une tarification créée en ligne. Chaque élément accepte exactement l’un des champs variant_id ou variant :
La création d’une variante nécessite plan:create en plus de payment:charge. La réutilisation d’une variante correspondante via product_id ne nécessite que payment:charge. Une définition product en ligne nécessite aussi access_pass:create pour créer le produit, ou access_pass:update pour en mettre à jour un existant. Les variantes doivent appartenir au compte du paiement et respecter les règles de compatibilité du panier. La variant en ligne utilise le même comportement « trouver ou créer » qu’une variant de premier niveau. Transmettez force_create_new_plan: true pour forcer la création d’une nouvelle variante. Les champs imbriqués de variante et de produit suivent Api-Version-Date, et les propriétés inconnues sont rejetées. Utilisez une Idempotency-Key pour rejouer la requête sans créer d’autre paiement.Pour appliquer une réduction, transmettez l’ID de l’un de vos codes promo dans promo_code_id, et Whop calcule le prix réduit pour vous. Le code promo doit être actif et valide pour la variante, et la variante doit appartenir à un produit.
3

Gérer les événements de paiement

Écoutez les webhooks de paiement pour suivre les réussites et les échecs.

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 transmettez setupFutureUsage: "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é.
1

Monter le formulaire avec le consentement d'enregistrement

Créer un checkout avec les éléments de paiement détaille le bouton de paiement, createConfirmationToken et handleNextAction.
2

Créer le paiement avec le jeton de confirmation

La réponse de création correspond au paiement tel qu’ouvert, pas à son issue. Le payment_method_id du moyen enregistré arrive dans le webhook payment.succeeded une fois le débit finalisé.
3

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

Des checkouts ponctuels et d’abonnement à associer à votre parcours d’enregistrement.

Élément Checkout

Montez le checkout Whop sur votre propre site avec Whop Elements.

Écouter les webhooks

Suivez setup_intent.succeeded, payment.succeeded et payment.failed.

Portail de facturation

Permettez aux clients de gérer et de supprimer leurs moyens de paiement enregistrés.