Skip to main content
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 :

Options

Transmettez-les à whop.payments.create({ … }), ou comme props sur <Payments> avec React.
Transmettez exactement l’une de ces combinaisons :
  • accountId et plan
  • accountId, currency et amount
  • accountId, mode: "setup" et currency
  • aucun de plan, currency, amount ou mode
string
ID du compte, préfixé par biz_. Ne l’omettez que pour appeler des méthodes statiques sans surface de compte.
"payment" | "setup"
Mode de montage, payment par défaut. setup enregistre un moyen de paiement sans rien débiter, ni maintenant ni plus tard : seuls les moyens pouvant être enregistrés sont proposés et les limites de montant ne s’appliquent pas. Confirmez avec createConfirmationToken(), puis créez le setup intent côté serveur.
string
ID du plan, préfixé par plan_. Il est résolu côté client en devise, montant et configuration des moyens de paiement. Transmettez un plan ou une devise et un montant inline, jamais les deux.
object
Totaux feeInclusive et feeFree en unités mineures, utilisés pour filtrer les moyens de paiement lorsque le checkout recalcule amount pour un moyen sans frais comme le BNPL. Chaque moyen est comparé à son total correspondant, ce qui évite que le moyen sans frais sélectionné disparaisse. S’ils sont omis, amount filtre tous les moyens.
string
URL de retour pour les étapes bancaires ou 3DS hors site. Par défaut, la page de montage. L’acheteur y arrive quel que soit le résultat, avec payment (ou setup), status (succeeded, failed, canceled ou un statut encore en attente comme processing) et client_secret ajoutés : vérifiez donc status avant d’afficher une page de succès.
"off_session" | "on_session"
Un setup enregistre le moyen de paiement pour un usage off_session, le seul usage qu’un setup accepte.
WalletAvailability
Remplacement de la disponibilité des wallets pour des aperçus déterministes. Les checkouts réels interrogent l’hôte.
string
Code de devise ISO 4217 à trois lettres en minuscules. Il filtre la matrice des moyens de paiement.
number
Montant du paiement en unités mineures. Les moyens dont les limites l’excluent ne sont pas proposés.
object
Filtres des moyens de paiement du compte au format enabled, disabled et include_platform_defaults de l’API. disabled retire des types, enabled rétablit des types proposés, et include_platform_defaults: false ne conserve que les types activés. Les plans fournissent leur propre configuration.
Appearance
Personnalisation visuelle des éléments de ce groupe. Remplace le WhopElements({ appearance }) global. Modifiez-la en direct avec update({ appearance }).
WhopElementsLocale
Langue des textes d’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 se rabat sur la langue par défaut.

Événements

Transmettez les callbacks dans les options de création ou dans les props React.

onLoadingChange

S’exécute lorsque l’état de chargement groupé change. La valeur vaut true tant qu’un élément monté est encore en cours de chargement.
boolean

Méthodes

Appelez-les sur le handle Payments obtenu avec whop.payments.create({ … }) ou usePayments().

createConfirmationToken

Crée un jeton de confirmation pour le moyen sélectionné depuis votre bouton de paiement. Transmettez les informations de facturation du checkout. Elles doivent inclure email. Fournissez phone pour les moyens qui l’exigent lorsque la collecte des informations de facturation est désactivée. Les cartes nécessitent aussi name et une adresse contenant line1 et country. Les sélections de wallet ouvrent leur feuille de paiement pendant l’interaction avec le bouton de paiement. Lorsque le compte propose la liaison bancaire dans la page (bank_debit.bank_connection sur son type de moyen de paiement par compte bancaire), la sélection d’un compte bancaire ouvre aussi Plaid Link à ce moment-là, et l’appel se résout une fois que l’acheteur a lié un compte. Cela nécessite une page whop.com ou un domaine prêt pour Apple Pay via l’API Domains, ainsi qu’une Content Security Policy qui autorise les hôtes Plaid renvoyés par contentSecurityPolicy(). Sinon, l’acheteur lie le compte après l’envoi. Si l’acheteur ferme la feuille ou Link, l’appel est rejeté avec payment_request_cancelled : traitez-le comme une annulation, et non comme une erreur de paiement, et laissez l’acheteur payer à nouveau. Confirmez le confirmationToken renvoyé côté serveur, puis appelez WhopElements.payments.handleNextAction(…). S’exécute sur votre page (côté hôte), et non dans l’iframe du contrôleur. Paramètres
object
requis
Renvoie Promise<object>
string
requis
string
requis

update

Fusionne les nouvelles options du handle dans chaque élément monté. Avec React, modifiez plutôt les props du namespace. Paramètres
Partial<PaymentsOptions>
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é.

Méthodes statiques

Appelez-les sans montage : whop.payments.<method>(…) en JavaScript vanilla ou useWhop().payments.<method>(…) avec React.

handleNextAction

Termine l’étape en attente d’un paiement confirmé sans monter d’élément. clientSecret identifie le paiement. Vous n’avez pas besoin d’ID de paiement. Les étapes inline s’ouvrent dans une boîte de dialogue et se résolvent avec redirected: false. Fermer la boîte de dialogue renvoie le statut actuel du paiement, qui peut rester en attente. Les étapes pleine page redirigent avec redirected: true vers return_url, ou vers un reçu hébergé lorsque le paiement n’a pas d’URL de retour. Dans une iframe, elles naviguent dans l’onglet de premier niveau. Si la page d’intégration refuse cette navigation, elles sont rejetées avec le code TAB_NAVIGATION_BLOCKED, et le paiement reste en attente. Définissez returnUrl pour mettre à jour la destination avant l’affichage. Un échec de mise à jour entraîne un rejet avant l’exécution de toute étape. Les étapes inline ne naviguent jamais vers cette URL. Un paiement dont le débit est encore en cours de décision est interrogé jusqu’à ce qu’une étape apparaisse ou qu’il soit réglé ; un paiement décidé sans étape se résout immédiatement. Paramètres
object
requis
Renvoie Promise<object>
string
requis
boolean
requis
object | null
requis

Ressources

Créez ces objets du SDK sans monter d’élément. Chacun a sa propre page :

PaymentRequest

Feuille de paiement Apple Pay, Google Pay ou PayPal de bas niveau pour les boutons personnalisés, le checkout express et les callbacks de livraison. Les tuiles de wallet automatisent ce flux via payments.createConfirmationToken. Attendez canMakePayment() pour vérifier la disponibilité et préparer le wallet, puis appelez show(type) de manière synchrone dans le handler d’interaction utilisateur. Le ctok résolu est un jeton de confirmation préfixé par ctok_. Confirmez-le côté serveur comme un jeton généré par un élément. Un jeton PayPal débite au maximum le total que PayPal a affiché à l’acheteur.

Content Security Policy

Une partie du travail de ce groupe s’exécute sur votre page, pas dans un frame. Une page dotée d’une Content Security Policy a besoin de ces sources. contentSecurityPolicy() de @whop/elements renvoie toutes les sources de ce tableau. La source sandbox s’applique avec environment: "sandbox".

Éléments

Les éléments que monte ce groupe. Chacun a sa propre page :

AddressElement

Collecte une adresse de facturation ou de livraison. Les champs, leur ordre et leur validation suivent le pays sélectionné. Inclut l’autocomplétion de la rue (en plein écran sur téléphone) et des méthodes pour lire ou valider l’adresse.

EmailElement

Collecte l’e-mail de l’acheteur et le transmet à payments.createConfirmationToken() tant qu’il est monté. Un billingDetails.email explicite est prioritaire. Un compte Whop correspondant affiche une connexion facultative avec vérification par code, ou avec la passkey du compte lorsqu’il en possède une. Une connexion réussie débloque les moyens de paiement enregistrés dans l’élément de paiement. Les acheteurs peuvent continuer en tant qu’invités.

TaxIdElement

Collecte un numéro d’identification fiscale d’entreprise accepté par l’API. Les libellés utilisent les noms présentés à l’acheteur. Le placeholder correspond au format sélectionné. country présélectionne un type. onChange émet les paires validées. L’hôte fournit les erreurs de validation de l’API.

BrandingElement

Obligatoire — les autres éléments, sauf AddressElement, EmailElement et TaxIdElement, l’attendent. La mention de marchand officiel (merchant of record) de Whop : l’acceptation par l’acheteur des conditions d’utilisation acheteur et de la politique de confidentialité de Whop, avec le logotype Whop. Obligatoire — les éléments de paiement, de carte et de champs de carte restent dans leur état de chargement tant qu’il n’est pas monté, et les paiements ne peuvent pas être confirmés sans lui.
Alternatives. Montez-en un seul à la fois. Détruisez-le avant d’en monter un autre :

PaymentElement

Affiche les moyens de paiement disponibles et collecte les champs requis et les mentions du moyen sélectionné. Utilisez change pour activer votre bouton de paiement. Dans son handler d’activation, appelez payments.createConfirmationToken(). Confirmez le jeton côté serveur, puis transmettez toute étape en attente à payments.handleNextAction(…). Utilisez addressChange pour les mises à jour dépendant de l’adresse.

CardElement

Champs préagencés pour le numéro de carte, la date d’expiration et le code de sécurité. Créez-le avec payments.create("card"), activez votre bouton de paiement depuis onChange et confirmez avec payments.createConfirmationToken(). Les numéros de carte restent dans des champs hébergés isolés PCI. layout prend en charge stacked (par défaut) et compact.

CardFields

Trois champs de carte isolés PCI, montables séparément, pour des mises en page personnalisées : numéro, date d’expiration et code de sécurité. Créez-le avec payments.create("cardFields"), placez chaque champ, activez votre bouton de paiement depuis onChange et confirmez avec payments.createConfirmationToken(). Les numéros de carte restent dans des champs hébergés. (sous-contrôleur, 3 éléments)