Pilote un checkout hébergé complet pour un ou plusieurs plans — récapitulatif de prix détaillé, codes promo, devise dans laquelle l’acheteur paie, et toute l’interface de collecte du paiement (les éléments de paiement, composés à l’intérieur) — via l’API des sessions de checkout Whop. Montez-le avec items, un seul plan ou une checkoutConfiguration que vous avez créée, et l’élément ouvre lui-même la session de checkout ; l’identifiant de session ne quitte jamais l’élément. Une configuration de checkout en mode setup monte le même élément pour enregistrer un moyen de paiement : rien n’est débité, le moyen de l’acheteur est conservé pour que vous puissiez le débiter plus tard, et le checkout terminé redirige avec setup_intent_id. L’acheteur paie à l’intérieur de l’élément, et un checkout terminé redirige l’onglet courant vers returnUrl, y compris la page qui contient l’élément. Exécutez les commandes à partir des webhooks plutôt que d’un callback navigateur. Sans returnUrl, l’acheteur reste sur la vue de succès propre à l’élément. L’élément pilote automatiquement une étape de paiement externe, comme 3DS ou une page bancaire. Sur whop.com, il ramène l’acheteur dans le checkout restauré ; dans une intégration, l’acheteur revient sur la même returnUrl quel que soit le résultat, avec les paramètres de requête payment et status (succeeded, failed ou canceled), donc la page de returnUrl doit lire status avant de considérer la visite comme une vente. Un paiement qui échoue à l’intérieur de l’élément rouvre le même checkout en affichant la raison, pour que l’acheteur puisse payer à nouveau. Chaque option est définie à la création : l’élément génère une session de checkout à partir de ces valeurs lors du montage. En modifier une plus tard avec update() ou de nouvelles props React échoue au lieu de modifier la commande existante. Montez un nouveau checkout pour changer ce qui est acheté.
Cette page documente @whop/elements@1.10.0 et @whop/elements-react@1.10.0.
Depuis v1.0.0.
Playground
Assemblez les éléments avec des données d’exemple. Manipulez les contrôles, ajoutez et organisez des éléments, et observez les événements se déclencher en direct :
import { WhopElements, Checkout } from "@whop/elements-react";import { loadWhop } from "@whop/elements";function Example() { return ( <WhopElements elements={loadWhop()}> <Checkout /* options */> {/* mount elements here */} </Checkout> </WhopElements> );}
Transmettez-les à whop.checkout.create({ … }), ou comme props sur <Checkout> avec React.
string
ID d’un plan existant, préfixé par plan_. Raccourci pour un tableau items contenant ce plan et quantity. Le plan définit le prix ; aucun montant ne peut être imposé côté client. Transmettez soit plan, soit items, soit une checkoutConfiguration. Défini uniquement à la création : la session est générée à partir de cette valeur, et toute modification ultérieure est refusée.
number
Le nombre d’unités à acheter. Les plans qui n’autorisent pas les multiples refusent les valeurs supérieures à 1. Défini uniquement à la création : la session est générée avec cette valeur, et toute modification ultérieure est refusée. @default 1
CheckoutItemInput[]
Les plans de ce checkout et le nombre d’unités à acheter pour chacun. Chaque article doit appartenir au même vendeur et utiliser des conditions de facturation compatibles ; l’API valide le panier complet et le facture en un seul débit. Transmettez cette option à la place de plan, quantity ou checkoutConfiguration. Défini uniquement à la création : la session est générée à partir de ce panier exact, et toute modification ultérieure est refusée.
Afficher propriétés
string
requis
ID d’un plan existant, préfixé par plan_.
number
Nombre d’unités à acheter. 1 par défaut ; les plans peuvent interdire les quantités supérieures à 1.
string
ID d’une configuration de checkout existante, préfixé par ch_. L’élément crée la session de checkout à partir de celle-ci : la configuration désigne le plan vendu (ou, en mode setup, aucun plan — le checkout enregistre un moyen de paiement et ne débite rien) et initialise ses propres code d’affiliation, métadonnées, redirection et préréglages de moyens de paiement — une option transmise ici à côté prévaut sur la valeur de la configuration, champ par champ. Transmettez plan en parallèle uniquement pour définir quantity ; il doit s’agir du plan propre à la configuration, qui ne peut jamais être remplacé à l’insu de ses préréglages. Défini uniquement à la création.
string
Un code promo à appliquer avant même que l’acheteur ne voie le prix — la réduction figure dans le premier devis, et l’acheteur peut encore la modifier ou la retirer. Transmettez le code porté par un lien marketing : un code expiré ou qui n’a jamais été valide ouvre le checkout au prix plein avec la raison sur la ligne promo, jamais un checkout qui refuse de s’ouvrir. Défini uniquement à la création.
string
L’affilié auquel ce checkout est attribué. Défini uniquement à la création.
CheckoutAttributionInput
La provenance de cette vente, pour les rapports du compte : les paramètres de campagne du lien par lequel l’acheteur est arrivé (utmSource, utmMedium, utmCampaign, utmTerm, utmContent, tout autre paramètre utm_* sous utm, un trackingLinkId Whop, un funnelId et votre propre source). Tout ce qui figure ici est enregistré sur la commande et n’est jamais montré à l’acheteur. Défini uniquement à la création.
Afficher propriétés
string
string
string
string
string
string
string
string
Record<string, string>
Tout autre paramètre utm_* porté par le lien, indexé par son nom complet ({ utm_funnel: 'spring' }). Les clés qui ne commencent pas par utm_ sont ignorées, et les champs nommés ci-dessus prévalent sur la même clé ici.
Record<string, string>
Vos propres paires clé/valeur à enregistrer sur la commande et à relire sur le paiement — ID de commande, ID de panier, ou tout ce que vous rapprochez. Jusqu’à 40 paires de chaînes. Défini uniquement à la création.
string
L’endroit où l’acheteur arrive après une étape de paiement externe, quel qu’en soit le résultat. L’onglet arrive avec payment (l’ID pay_ ; setup avec l’ID sint_ pour un checkout en mode setup) et status (succeeded, failed ou canceled) ajoutés, et vos autres paramètres de requête intacts. Branchez votre logique sur status avant d’afficher une page de succès : une étape externe refusée ou abandonnée arrive aussi ici. Exécutez les commandes à partir des webhooks, pas à partir de cette visite. HTTPS uniquement (http pour localhost). Défini uniquement à la création.
Appearance
Personnalisation visuelle des éléments de ce groupe. Remplace le WhopElements({ appearance }) global. Modifiez-la en direct avec update({ appearance }).
WhopElementsLocale
Langue du texte de l’interface des éléments de ce groupe. Définissez-la sur l’une des langues intégrées à l’application pour remplacer la configuration globale. Toute autre valeur revient à la langue par défaut.
Événements
Transmettez les callbacks dans les options de création ou dans les props React.
onComplete
Se déclenche une fois par montage lorsque le checkout se termine et que son résultat est confirmé. result indique ce qui est confirmé : payment (l’acheteur a payé — paymentId), waitlist_entry (l’acheteur a rejoint une liste d’attente — entryId) ou setup (un checkout en mode setup a enregistré le moyen de paiement — setupIntentId) ; sessionId est la session de checkout dans tous les cas. Se déclenche avant toute navigation vers returnUrl : c’est donc là que vos propres outils d’analyse ou pixels publicitaires enregistrent l’achat. Exécutez les commandes à partir des webhooks, pas de ce callback : un checkout restauré lors d’un chargement de page ultérieur le déclenche à nouveau pour le même résultat.
Le paiement, préfixé par pay_ — l’ID sous lequel enregistrer l’achat.
Masquer CheckoutWaitlistCompletion
string
requis
La session de checkout, préfixée par chs_.
"waitlist_entry"
requis
string
requis
L’entrée de liste d’attente, préfixée par ent_.
Masquer CheckoutSetupCompletion
string
requis
La session de checkout, préfixée par chs_.
"setup"
requis
string
requis
Le setup enregistré, préfixé par sint_.
onLoadingChange
S’exécute lorsque l’état de chargement groupé change. La valeur est true tant qu’un élément monté est encore en cours de chargement.
boolean
Méthodes
Appelez-les sur le handle Checkout obtenu via whop.checkout.create({ … }) ou useCheckout().
update
Fusionne de nouvelles options de handle dans chaque élément monté. Avec React, modifiez plutôt les props du namespace.Paramètres
Partial<CheckoutOptions>
requis
destroy
Détruit chaque élément et sous-contrôleur créé par ce handle, supprime le frame du contrôleur et libère ses abonnements. Vous pouvez l’appeler plusieurs fois, mais un handle détruit refuse tout autre appel — créez un nouveau handle pour recommencer. React supprime le groupe automatiquement lorsque le provider est démonté.
Ressources
Créez ces objets SDK sans monter d’élément. Chacun a sa propre page :
CheckoutSession
Session de checkout headless de bas niveau pour une page qui affiche son propre bouton PayPal. load() crée la session de checkout à partir de lineItems ; show("paypal", { termsAccepted: true }) envoie l’acheteur vers PayPal — une fenêtre pop-up sur ordinateur, l’onglet entier sur téléphone — et se résout avec le paiement une fois que l’acheteur a approuvé. Avec paymentMethodOptions.paypal.requestShipping, PayPal demande une adresse de livraison à l’acheteur et le webhook du compte abonné à shipping_address.changed calcule le prix de chacune sur votre serveur pendant que l’acheteur est sur PayPal ; le paiement n’est créé qu’après l’approbation de l’acheteur, à ce prix. Après une redirection pleine page, la promesse ne se résout jamais ; lisez plutôt le résultat dans les paramètres de requête payment et status de redirectUrl.
Éléments
Les éléments montés par ce groupe. Chacun a sa propre page :Alternatives. Montez-en un seul à la fois. Détruisez-le avant d’en monter un autre :
CheckoutElement
L’interface de paiement complète — récapitulatif de commande avec le devis en temps réel, saisie du code promo, devise dans laquelle l’acheteur paie, tout ce que ce checkout doit collecter auprès de l’acheteur, l’interface composée des moyens de paiement et le flux de paiement. Ce qu’il collecte correspond à ce que le vendeur a configuré (e-mail, ses propres questions, un numéro de téléphone, une adresse de livraison pour les biens physiques, une acceptation explicite de ses conditions), affiché ensemble sur un seul écran dans l’ordre choisi — ainsi, un vendeur qui commence à demander quelque chose de nouveau n’a rien à modifier ici. Affiche l’intégralité de l’achat ; le contrôleur de checkout gère la session et l’identifiant. Après un paiement nécessitant une étape externe, cette même interface affiche le résultat signalé par le serveur lorsque l’acheteur revient.
ExpressCheckoutElement
Des boutons Apple Pay, Google Pay et PayPal en un clic pour un checkout — le wallet collecte tout ce dont la session a encore besoin (l’e-mail de l’acheteur, une adresse de livraison pour les biens physiques, un numéro de téléphone lorsque le vendeur en collecte un dans Apple Pay et Google Pay, et dans Apple Pay un code promo lorsque le vendeur propose sa saisie) et un seul clic finalise l’achat. Il partage l’emplacement d’entrée du checkout avec l’élément de checkout complet, de sorte qu’un handle monte exactement l’un des deux : ce bouton seul lorsque l’achat est assez simple pour qu’une feuille de paiement le finalise, ou l’interface de checkout complète pour tout le reste. N’affiche que les wallets avec lesquels l’appareil de l’acheteur peut réellement payer — et que la configuration des moyens de paiement du checkout autorise — en utilisant les visuels de boutons fournis, et n’affiche rien lorsqu’aucun wallet n’est disponible. PayPal apparaît lorsque le vendeur l’accepte, s’ouvre dans sa propre fenêtre et enregistre le compte PayPal de l’acheteur avec l’achat, de sorte qu’un renouvellement, un essai gratuit et les débits ultérieurs du vendeur fonctionnent comme avec une carte enregistrée. Les trois wallets nécessitent Apple Pay sur le domaine de la page : les pages first-party whop.com sont pré-approuvées, et tout autre site doit ajouter Apple Pay à son domaine via l’API Domains avant que l’un de ces boutons puisse s’y afficher. Proposer Google Pay sur votre propre site est soumis aux conditions d’utilisation de l’API Google Pay. Un checkout que la feuille de paiement ne peut pas honnêtement finaliser — une inscription à une liste d’attente, un transfert, une question de formulaire que seule une page peut poser — est refusé de manière explicite au lieu d’afficher un bouton voué à l’échec.
Assistant
Responses are generated using AI and may contain mistakes.