Encaissez un paiement à partir d’un ID plan_ ou d’une devise et d’un montant inline, ou enregistrez un moyen de paiement sans débit avec mode: "setup". Montez PaymentElement, CardElement ou CardFields, puis appelez payments.createConfirmationToken avec les informations de facturation. Les sélections de wallet ouvrent automatiquement leur feuille 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 sur la page. Si l’acheteur ferme l’un ou l’autre, l’appel est rejeté avec payment_request_cancelled, que votre handler de paiement doit traiter comme une annulation. Confirmez le jeton côté serveur, puis transmettez le client_secret du paiement ou du setup intent à handleNextAction pour toute étape en attente.
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, Payments } from "@whop/elements-react";import { loadWhop } from "@whop/elements";function Example() { return ( <WhopElements elements={loadWhop()}> <Payments /* options */> {/* mount elements here */} </Payments> </WhopElements> );}
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.
Afficher propriétés
number
requis
number
requis
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.
Afficher propriétés
boolean
requis
boolean
requis
boolean
("apple_pay" | "google_pay" | "paypal_express")[]
Les wallets classés selon la feuille de paiement native de ce navigateur — Apple Pay en premier sur WebKit, Google Pay en premier partout ailleurs, PayPal en dernier — pour que les boutons express puissent s’empiler du meilleur au moins bon. Absent lorsque la disponibilité est déclarée par l’intégrateur (aperçus) et sur les échanges antérieurs à ce champ. Une union inline, et non le WalletSheetType de payment-request : ce module importe déjà celui-ci.
object
Les détails de chaque wallet disponible, indexés par type de wallet. Absent lorsque la disponibilité est déclarée par l’intégrateur (aperçus).
Afficher propriétés
WalletDetails
Afficher propriétés
WalletButtonArt
Le visuel de bouton officiel du wallet. Absent lorsqu’aucun n’est publié.
Afficher propriétés
object
requis
Pour les pages claires.
Afficher propriétés
string
requis
string
requis
object
requis
Pour les pages sombres.
Afficher propriétés
string
requis
string
requis
WalletDetails
Afficher propriétés
WalletButtonArt
Le visuel de bouton officiel du wallet. Absent lorsqu’aucun n’est publié.
Afficher propriétés
object
requis
Pour les pages claires.
Afficher propriétés
string
requis
string
requis
object
requis
Pour les pages sombres.
Afficher propriétés
string
requis
string
requis
WalletDetails
Afficher propriétés
WalletButtonArt
Le visuel de bouton officiel du wallet. Absent lorsqu’aucun n’est publié.
Afficher propriétés
object
requis
Pour les pages claires.
Afficher propriétés
string
requis
string
requis
object
requis
Pour les pages sombres.
Afficher propriétés
string
requis
string
requis
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.
Afficher propriétés
string[]
string[]
boolean
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
Masquer propriétés
object
Afficher propriétés
string
string
string
object
Afficher propriétés
string
string
string
string
string
string
RenvoiePromise<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
Masquer propriétés
string
requis
string
number
RenvoiePromise<object>
string
requis
boolean
requis
object | null
requis
Afficher propriétés
string | null
string | null
string | null
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".
Besoin
Directive
Source en production
Source en sandbox
Script de Plaid Link
script-src
https://cdn.plaid.com
Identique
↳ Frame de Plaid Link, ouvert par le script de Plaid
frame-src
https://cdn.plaid.com
Identique
↳ API de Plaid, appelée par le script de Plaid
connect-src
https://production.plaid.com
https://sandbox.plaid.com
É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)
Assistant
Responses are generated using AI and may contain mistakes.