Skip to main content
Cette page documente @whop/elements@1.10.0 et @whop/elements-react@1.10.0.
Depuis v1.0.0.
Se monte à l’intérieur de Payments. Transmettez les props et les callbacks via les options de création ou les props React. Conservez le handle créé, ou la ref React, pour appeler select().
Exclusif. PaymentElement est une alternative à CardElement ou CardFields dans ce handle Payments. Montez-en un seul à la fois. Détruisez-le avant d’en monter un autre.
Attend BrandingElement. Cet élément reste dans son état de chargement jusqu’à ce que BrandingElement soit monté dans le même handle Payments.
Se monte à l’intérieur d’un scope WhopPayments. Affiche les tuiles des moyens proposés par le débit, puis ce que collecte le moyen sélectionné : les champs de carte, les champs qu’il déclare ou le bouton Apple Pay.
Montez-le à l’intérieur de <Payments>, qui gère le débit et le jeton de confirmation. <Payments> se monte lui-même à l’intérieur de <WhopElements>. Il affiche les tuiles des moyens du débit et collecte tout ce que déclare le moyen sélectionné : une carte, une feuille de wallet et une redirection bancaire tiennent donc en une seule et même ligne.

Données d’exemple. Ouvrir le Playground.

Props

string[]
Contrôle l’ordre d’affichage dans les deux dispositions. Les types listés apparaissent en premier, dans l’ordre. Les types non listés conservent leur ordre relatif. N’affecte pas la disponibilité. Par défaut : [].
object
Contrôle les wallets proposés par l’élément. Chaque clé vaut par défaut 'auto', qui propose le wallet partout où le compte, l’appareil de l’acheteur et le débit le prennent en charge. 'never' retire ce wallet de la liste des moyens. Utilisez-le lorsque votre page affiche ses propres boutons Apple Pay, Google Pay ou PayPal avec paymentRequest, afin que les acheteurs ne voient chaque wallet qu’une fois. payPal: 'never' retire le moyen PayPal. Les moyens de paiement enregistrés ne sont pas concernés. Par défaut : {}. Depuis v1.8.0.
object
Contrôle la collecte des informations de facturation. billingDetails: 'minimal' (par défaut) suit la matrice de chaque moyen. Par défaut, les moyens collectent le nom et le format complet du pays. Une surcharge peut ne collecter que le minimum déclaré, ou rien du tout. Pour les cartes, le minimum est le nom sur la carte, le pays et le code postal. 'full' exige le nom et le format complet du pays pour chaque nouveau moyen. 'never' masque le bloc. address: 'minimal' ne collecte que le minimum déclaré de chaque moyen, plus un pays lorsque ce minimum n’en comporte pas (et aussi le code postal lorsque billingDetails: 'full' indique que le checkout est soumis à taxe), sauf pour les wallets, la crypto, les prélèvements bancaires, les virements bancaires, les paiements par carte en présentiel et les achats intégrés, qui ne collectent aucune adresse, et sauf pour un moyen dont le prestataire exige l’adresse de facturation complète (requires_full_billing_address), dont la tuile suit les mêmes règles qu’un checkout sans indicateur ; dans les autres cas, il l’emporte sur billingDetails: 'full' ; utilisez-le lorsque le vendeur ne collecte pas d’adresse de facturation complète. phone: 'never' masque uniquement le champ de téléphone de facturation lorsque votre formulaire le collecte déjà ; transmettez billingDetails.phone à createConfirmationToken pour les moyens qui l’exigent. Transmettez plutôt l’adresse à createConfirmationToken. Le sélecteur de pays n’inclut que les pays pris en charge par le moyen et la devise de paiement. Lorsqu’un plan de paiement échelonné est sélectionné, il se limite aux pays desservis par ce plan — le pays de facturation est le pays de transaction sous lequel le débit est traité. Il se verrouille lorsqu’un seul pays est disponible. Par défaut : {"billingDetails":"minimal"}.
object
Préremplit les informations de facturation lors du premier affichage du bloc de facturation de chaque moyen. L’acheteur peut modifier chaque champ prérempli. address.country est un code ISO 3166-1 alpha-2 et ne s’applique que lorsque le moyen sélectionné l’accepte. phone remplit le champ de téléphone de facturation pour les moyens qui en collectent un, au format E.164 comme +14155552671 ; un numéro hors des pays de téléphone pris en charge par le moyen est ignoré. Seuls les champs affichés par le bloc sont préremplis et envoyés. Transmettez tout le reste à createConfirmationToken dans billingDetails. Depuis v1.1.0.
"accordion" | "horizontal"
Disposition du sélecteur. accordion (par défaut) empile les moyens et déplie les détails inline. horizontal affiche des tuiles de largeur égale, sans défilement, avec les détails du moyen sélectionné en dessous. Au-delà de quatre moyens, une tuile More ouvre un sélecteur natif. Le moyen choisi à cet endroit occupe la dernière tuile jusqu’à la sélection suivante. La sélection et la confirmation se comportent de la même manière. Par défaut : "accordion".
boolean
accordion uniquement. Ajoute de l’espacement et un style de carte distinct entre les moyens. Ignoré lorsque layout vaut horizontal. Par défaut : false.
boolean
Indique s’il faut sélectionner le premier moyen proposé après la résolution. La valeur par défaut true respecte order et émet selected et change comme une interaction de l’acheteur. Elle s’exécute une seule fois avant toute interaction de l’acheteur et ne fait rien lorsqu’aucun moyen n’est proposé. Définissez false pour monter l’élément sans sélection. Indépendamment, si une mise à jour retire le moyen sélectionné, la sélection revient au premier moyen proposé. Un élément déjà sans sélection le reste. Par défaut : true.

Événements

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

onChange

Se déclenche lorsque la sélection change. complete: true signifie que l’acheteur a sélectionné un moyen et rempli ses champs de carte ou ses champs obligatoires. Utilisez-le pour activer la confirmation. paymentMethod est le moyen de paiement sélectionné, enregistré ou nouveau, ou null tant que rien n’est sélectionné : displayName et icons nomment le choix tel que l’élément l’affiche (avec balance.imageUrl, l’image du propriétaire d’un solde), card contient le réseau d’une carte, ses quatre derniers chiffres et son type de financement, requiresBillingPhone indique si le moyen nécessite un téléphone dans les informations de facturation, et countries liste les pays depuis lesquels le moyen peut payer dans la devise du débit. type, requiresBillingPhone et method au niveau supérieur sont dépréciés : lisez-les depuis paymentMethod. supportsBuyerFee au niveau supérieur est également déprécié, sans remplacement : Whop fixe lui-même le prix de ses frais de service acheteur.
PaymentElementChangeEvent

onAddressChange

Se déclenche environ 300 ms après la modification de l’adresse de facturation interne. Utilisez-le pour les taxes, la livraison ou d’autres mises à jour dépendant de l’adresse. country est un code ISO 3166-1 alpha-2. Le payload omet les autres clés d’adresse lorsqu’elles sont vides ou inutilisées pour ce pays. complete: true signifie que le bloc de facturation est valide et complet. Cet événement ne se déclenche que tant que l’élément de paiement gère la collecte de l’adresse. Avec fields.billingDetails: 'never', utilisez votre propre source d’adresse. Avec un AddressElement monté, utilisez son événement change.
object

onLoaderStart

S’exécute après le premier affichage du squelette de chargement et avant onReady.

onReady

S’exécute après le premier affichage complet de l’élément.

onError

S’exécute lorsque l’élément ne parvient pas à se charger ou plante. L’affichage de repli reste visible. Utilisez code pour une gestion programmatique. sourceKey identifie une source d’état hôte en échec.
object

Méthodes

Appelez-les sur le handle renvoyé par create, ou via une ref React.

select

Sélectionne un moyen par le même chemin qu’une interaction de l’acheteur. Par exemple, select('cashapp') déplie la tuile et émet selected et change. Les cartes restent à complete: false tant que leurs champs ne sont pas remplis. Les moyens inconnus, indisponibles ou soumis à une condition de montant sont rejetés avec le code METHOD_NOT_OFFERED. select(null) efface la sélection et émet change avec complete: false. À utiliser avec autoSelect={false} pour un contrôle externe complet.Paramètres
string | null
requis
Renvoie Promise<void>

mount

Monte l’élément dans target et démarre le chargement. Les composants React se montent eux-mêmes.Paramètres
string | HTMLElement
requis

destroy

Supprime l’élément et libère son frame et ses abonnements. Vous pouvez l’appeler plusieurs fois. React supprime l’élément automatiquement.

update

Fusionne de nouvelles props dans l’élément monté. Avec React, modifiez plutôt les props du composant.Paramètres
Partial<PaymentElementProps>
requis

Style

Stylisez ces parties via appearance.classes. Utilisez le camel case ou le kebab case pour les noms de propriétés et incluez les unités. Les feuilles de style de la page ne peuvent pas atteindre le frame de l’élément. Le framework valide chaque déclaration avant de l’injecter.
Avec React, transmettez appearance à <Payments>. Définissez-la globalement avec WhopElements({ appearance }).

Paramètres

[WhopPaymentMethodType]
Ordre des tuiles pour ce montage, qui remplace le methodOrder du contrôleur. Les types listés prennent leur position dans la liste ; les autres conservent leur ordre d’origine derrière eux.
Binding<WhopPaymentSelection>?
Relit la sélection actuelle et son état de complétude. Le contrôleur suit les deux dans tous les cas.

WhopPaymentSelection

Ce que renvoie une sélection :
  • isComplete: Bool : le moyen sélectionné dispose de tout ce dont il a besoin
  • type: WhopPaymentMethodType? : le moyen sélectionné
  • displayName: String? : son libellé, tel que l’écrit la matrice
  • category: String? : card, wallet, bank_debit, …

États

Affiche des tuiles squelettes pendant le chargement de la matrice des moyens, et le message d’échec lorsque la lecture échoue. Un moyen dont cette build ne peut pas exécuter la catégorie est ignoré plutôt qu’affiché sous forme de tuile défectueuse. Sélectionner un wallet remplace la surface de confirmation par Apple Pay.

Bon à savoir

  • Apple Pay n’a besoin de rien de la part de votre application : ni identifiant marchand, ni capacité In-App Payments. Le marchand est celui enregistré sur le compte Whop, et la tuile s’affiche dès que l’appareil peut payer.
  • Un moyen qui déclare un champ secure l’affiche sous forme de champ hébergé. Ces valeurs n’entrent jamais dans votre processus.
  • Les moyens enregistrés d’un acheteur connecté apparaissent au-dessus des nouveaux. Montez WhopEmailElement pour proposer la connexion qui produit l’identifiant ; choisir une ligne enregistrée ne collecte rien et génère une référence.
  • Un débit par carte qui publie des paliers de paiement échelonné affiche un sélecteur de plan dans le panneau de carte. Un plan que la carte de l’acheteur ne peut pas prendre est replié plutôt que grisé, et un plan dont la région ne correspond pas au pays de facturation est refusé avant l’exécution de tout tokenizer.
  • Un marché qui exige un document d’identité (un débit en ars, aujourd’hui) affiche le sélecteur de type et le champ de numéro dans le panneau. Ce numéro transite par votre application en route vers le tokenizer, contrairement à la carte, et n’atteint toujours jamais Whop.
  • Les valeurs de carte et des champs sécurisés sont tokenisées avant la génération du jeton, de sorte que le jeton de confirmation est la seule chose qui traverse votre application.
  • Montez WhopAddressElement à côté lorsqu’un moyen nécessite un pays de facturation : la liste des tuiles se limite aux moyens autorisés par ce pays.

Installation

Montez-le à l’intérieur d’un scope WhopPayments(accountID:charge:), qui crée le contrôleur et le transmet à son contenu. payments.buyer est l’acheteur connecté dès qu’une connexion par e-mail en a authentifié un. WhopBrandingElement doit aussi être à l’écran, car Whop est le marchand officiel (merchant of record) de ces ventes et createConfirmationToken refuse sans lui. Stylisez avec .whopElementsAppearance(_:). Le module est Elements, et non WhopElements du SDK wallet. Consultez Premiers pas et Apparence.

Props

string[]
Ordre d’affichage des moyens, avec la sémantique de paymentMethodOrder de Stripe. Les types non listés conservent leur ordre relatif d’origine derrière les types listés. Peut aussi être défini une fois sur <Payments>.
(payload: PaymentChangePayload) => void
Se déclenche à chaque changement de sélection et de complétude. Conditionnez votre bouton d’envoi à complete.
StyleProp<ViewStyle>
Appliqué à la View externe de l’élément. Pour la personnalisation du thème, préférez appearance.parts sur le provider, qui couvre tous les éléments de cette interface. Notez que les noms de parties React Native forment aujourd’hui leur propre ensemble, distinct des noms de classes whop-* du web : un objet appearance web ne peut donc pas être repris tel quel.
ReactNode
Affiché à la place du squelette intégré pendant le chargement de l’élément.
() => void
Se déclenche une fois que l’élément est interactif. <Payments> les regroupe, donc c’est généralement son propre onLoadingChange qu’il vous faut.
(error: { message: string; code?: string }) => void
Un échec de chargement ou de configuration pour cet élément. L’élément affiche sa propre vue d’erreur dans tous les cas.

PaymentChangePayload

Ce que renvoie onChange :
  • complete: boolean : le moyen sélectionné dispose de tout ce dont il a besoin
  • type?: string : le type du moyen sélectionné, par exemple card
  • method?: { type, category, template, display_name } : l’entrée de matrice du moyen sélectionné

États

Trois lignes squelettes jusqu’à l’arrivée de la matrice des moyens, puis les tuiles. Sélectionner une tuile déplie sa zone de détail en dessous. onChange signale complete lorsque le moyen sélectionné dispose de tout ce dont il a besoin, ce qui conditionne votre bouton d’envoi. Un débit sans moyen éligible affiche un état vide explicatif plutôt que rien.

Bon à savoir

  • Les numéros de carte ne passent jamais par votre code. Les champs sont des champs natifs isolés PCI, et le SDK transmet un jeton à Whop : votre application reste donc hors du périmètre PCI.
  • Apple Pay et Google Pay présentent tous deux la feuille native de la plateforme. Aucun des deux n’a besoin de quoi que ce soit de votre part : Apple Pay utilise le marchand enregistré sur le compte Whop, il n’y a donc aucun identifiant marchand à transmettre ni aucune capacité à ajouter dans Xcode, et googlePayMerchantName définit uniquement le nom affiché dans la feuille, qui vaut Whop par défaut.
  • Les moyens à redirection et 3D Secure ouvrent ASWebAuthenticationSession sur iOS et Custom Tabs sur Android. C’est le navigateur système, jamais une WebView, de sorte que la page de l’émetteur reste en dehors du périmètre de confiance de votre application.
  • Définissez returnUrl sur <Payments> avec une URL https que vous hébergez. L’API refuse tout ce qui n’est pas https ou loopback (PaymentsApi::ValidateReturnUrl), un schéma d’application personnalisé n’est donc pas disponible ici. Vous n’enregistrez pas de lien profond : après la redirection de l’émetteur, handleNextAction interroge le paiement jusqu’à son état final et ferme lui-même le navigateur.
Enveloppez votre application dans <WhopElements getToken={…}> une seule fois, puis montez <Payments> autour des éléments. Consultez Premiers pas et Apparence.