Skip to main content
Cette page documente @whop/elements@1.10.0 et @whop/elements-react@1.10.0.
Depuis v1.0.0.
Créez cette ressource Payments sans monter d’élément : whop.payments.paymentRequest.create({ … }) en JavaScript vanilla ou useWhop().payments.paymentRequest.create({ … }) avec React.

Options

Transmettez-les à whop.payments.paymentRequest.create({ … }).
string
requis
ID du compte, préfixé par biz_, auquel est limité chaque appel côté client.
string
requis
Code de devise de paiement ISO 4217 à trois lettres.
number
requis
Montant du paiement en unités mineures. Modifiez-le plus tard avec update().
"off_session" | "on_session"
À définir uniquement après avoir affiché le consentement à l’enregistrement. Marque le jeton pour une utilisation off_session ou on_session.
PaymentMethodConfigurationShape
Filtres de moyens de paiement au format enabled, disabled et include_platform_defaults de l’API. Ils restreignent les wallets signalés par canMakePayment() : disabled retire des types, enabled rétablit des types proposés, et include_platform_defaults: false ne laisse que les types activés. Ils n’ajoutent jamais un moyen que le compte ne propose pas. PayPal suit le type paypal. Depuis v1.9.0.
boolean
Demande l’e-mail du payeur dans la feuille — le jeton de confirmation en exige un. Par défaut : true.
boolean
Demande le numéro de téléphone du payeur dans la feuille, fourni sous la forme payer.phone dans le résultat — au format E.164 lorsqu’il peut être analysé selon le pays du contact qui l’a fourni, tel que le wallet l’a transmis sinon ; payer.country est le pays de facturation. Google Pay le collecte via l’adresse de facturation que la feuille demande déjà. PayPal le collecte via sa section de contact et refuse un compte qui n’en a pas. Par défaut : false.
boolean
Demande une adresse de livraison dans la feuille (et propose shippingOptions lorsqu’elles sont fournies). PayPal demande toujours une adresse, puisque c’est sur elle que la taxe est calculée, et ne la renvoie sous forme de shipping que lorsque cette option est définie. Par défaut : false.
boolean
Propose le champ de code promo propre à la feuille et répond à onPromoCodeChange. Apple Pay affiche le champ sur les appareils prenant en charge Apple Pay version 12 (iOS 15 et macOS 12) ; Google Pay l’affiche lorsque la configuration Google Pay du compte autorise les offres. Les autres appareils ouvrent la feuille sans ce champ. Par défaut : false. Depuis v1.5.0.
string
Un code promo déjà appliqué au débit, prérempli dans la feuille afin que l’acheteur puisse le voir, le remplacer ou le supprimer. Depuis v1.5.0.
string
L’effet de appliedPromoCode, affiché à côté du code dans Google Pay. Le champ de coupon d’Apple Pay n’a pas de légende. Depuis v1.5.0.
string
Code pays ISO 3166-1 alpha-2 du compte pour la feuille Apple Pay. Omettez-le pour utiliser le pays d’immatriculation publié du compte. La feuille utilise US par défaut lorsqu’aucun des deux n’est disponible.
PaymentRequestLineItem[]
Lignes d’articles que la feuille liste sous le total. Modifiez-les plus tard avec update().
PaymentRequestShippingOption[]
Options de livraison proposées par la feuille lorsque requestShipping est défini. Affichage uniquement — mettez à jour amount depuis votre gestionnaire de changement. La feuille s’ouvre avec la première option sélectionnée et ne déclenche aucun onShippingOptionChange pour celle-ci, donc amount doit déjà inclure son prix. Modifiez-les plus tard avec update().

Méthodes

Appelez-les sur la ressource.
Appelez show de manière synchrone pendant l’activation utilisateur. Attendez d’abord les prérequis.

canMakePayment

Renvoie la disponibilité de chaque wallet lorsque le compte le propose, que l’appareil le prend en charge et que l’origine de cette page est approuvée pour le compte (les pages first-party whop.com sont pré-approuvées ; une page marchande doit avoir Apple Pay prêt sur son domaine via l’API Domains, et y proposer Google Pay est soumis aux Conditions d’utilisation de l’API Google Pay). Sur une page elle-même intégrée dans une iframe, Apple Pay vérifie plutôt le domaine de la page de premier niveau lorsque le navigateur l’expose. Sur les navigateurs non WebKit, Apple Pay correspond au flux de transfert vers l’iPhone sur ordinateur, de sorte que les appareils mobiles le signalent comme indisponible — Apple Pay natif dans les navigateurs iOS n’est pas concerné. order classe les wallets selon la feuille native du navigateur — Apple Pay en premier sur Safari, Google Pay en premier ailleurs, PayPal en dernier — afin que les boutons express puissent être empilés du meilleur au moins bon. payPal signale PayPal lorsque le compte le propose dans cette devise, que le montant respecte les limites de PayPal, que la requête ne demande pas le téléphone du payeur (une requête off_session peut être de 0 $, ce qui enregistre PayPal sans débit), que les scripts de PayPal se chargent sur cette page et que l’origine de cette page est approuvée pour le compte, comme pour les autres wallets. Une page dotée d’une Content Security Policy doit autoriser les hôtes de PayPal, que contentSecurityPolicy() inclut. Une page qui charge déjà le SDK JavaScript v5 de PayPal signale payPal: false. Transmettez types pour ne vérifier que les wallets que vous listez ; show(type) nécessite que ce wallet ait été vérifié. wallets contient le visuel de bouton officiel de chaque wallet disponible (couleur et image light et dark). Cet appel prépare show(). Attendez-le toujours en premier.Paramètres
object
Renvoie Promise<WalletAvailability>
boolean
requis
boolean
requis
boolean
("apple_pay" | "google_pay" | "paypal_express")[]
Les wallets classés selon la feuille native de ce navigateur — Apple Pay en premier sur WebKit, Google Pay en premier partout ailleurs, PayPal en dernier — afin que les boutons express puissent être empilés du meilleur au moins bon. Absent pour une disponibilité déclarée par l’intégrateur (aperçus) et sur les versions du protocole antérieures à 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 pour une disponibilité déclarée par l’intégrateur (aperçus).

show

Ouvre le wallet sélectionné après avoir attendu canMakePayment(), de manière synchrone lors de l’appui : Apple exige que la session soit créée dans la pile du geste, et PayPal y ouvre sa fenêtre — une pop-up sur ordinateur, la fenêtre intégrée à la page de PayPal lorsque la pop-up est bloquée et sur mobile. Transmettez email lorsque votre page en a déjà collecté un — le wallet le reprend et n’en demande jamais un second. Avec requestPayerEmail: false, en transmettre un est obligatoire, et le wallet refuse de s’ouvrir sans lui car les jetons de confirmation exigent un e-mail. Tant que la feuille est ouverte, update() lève une exception : répondez aux événements de changement pour la modifier. Appelez de manière synchrone pendant l’activation utilisateur. Attendez d’abord les prérequis, car les navigateurs révoquent l’activation au fil des étapes asynchrones.Paramètres
"apple_pay" | "google_pay" | "paypal_express"
requis
object
Renvoie Promise<PaymentRequestResult>
string
requis
ID du jeton de confirmation, préfixé par ctok_. Confirmez-le côté serveur avec votre clé secrète.
"apple_pay" | "google_pay" | "paypal_express"
requis
object
requis
phone est au format E.164 lorsqu’il a pu être analysé selon le pays du contact, tel que fourni sinon ; PayPal n’en fournit un que pour requestPayerPhone, et refuse un compte qui n’en a pas. country est le pays de facturation que chaque feuille collecte.
object | null
requis
L’adresse de facturation complète contenue dans le jeton de confirmation, contrairement à l’adresse masquée transmise par les événements de changement ; null lorsque le wallet n’en a fourni aucune. Apple Pay et Google Pay fournissent l’adresse de facturation de la carte. Sur PayPal, il s’agit de l’adresse choisie par l’acheteur dans PayPal, celle sur laquelle son total a été taxé.
object | null
requis
null sauf si requestShipping a été défini. option est l’option de livraison sélectionnée : la première proposée jusqu’à ce que l’acheteur en choisisse une autre, et de nouveau la première lorsqu’une réponse a remplacé les options sans l’id choisi. Apple Pay et Google Pay la définissent dès que des options ont été proposées, PayPal jamais.

update

Modifie amount, lineItems et shippingOptions sur cette instance. Toutes les autres options sont fixées lors de create() : créez une nouvelle instance pour les modifier.Paramètres
object
requis

Événements

Abonnez-vous aux événements ci-dessous. Chaque méthode renvoie une fonction de désabonnement.
Chaque gestionnaire d’événement doit appeler sa méthode de réponse documentée exactement une fois. Un gestionnaire qui lève une exception ou est rejeté avant de répondre fait échouer cette mise à jour immédiatement.

onShippingAddressChange

L’acheteur a choisi une adresse de livraison (masquée avant autorisation : ville, état, code postal et pays uniquement ; Apple Pay réduit un code ZIP américain à cinq chiffres et supprime les trois derniers caractères d’un code postal canadien ou britannique). Répondez avec les totaux pour l’adresse et l’option de livraison sélectionnée : la première jusqu’à ce que l’acheteur en choisisse une autre. shippingOptions remplace les options (une liste vide ne change rien). Une option choisie reste sélectionnée tant que la réponse conserve son id ; lorsque la réponse la retire, la première option devient la sélection sans onShippingOptionChange, tarifez donc celle-ci. Chaque erreur de la réponse reste attachée à l’adresse jusqu’à ce qu’une réponse ultérieure pour une adresse l’efface : une erreur qui nomme un field (city, state, postal_code, country) marque ce champ dans Apple Pay, et Google Pay affiche le message seul. Le paiement est refusé tant qu’une erreur subsiste sur l’adresse. Refusez une adresse vers laquelle vous ne pouvez pas livrer avec une erreur shipping_address_unserviceable et sans field. Sur Apple Pay, Google Pay et PayPal, un gestionnaire qui n’a pas répondu dans les 25 secondes fait échouer l’adresse, comme le ferait un gestionnaire qui lève une exception, et sa réponse ultérieure est ignorée. PayPal le déclenche avec l’adresse choisie par l’acheteur, et une erreur nommant un field refuse cette partie de l’adresse dans PayPal. Appelez updateWith(…) exactement une fois par événement. Un gestionnaire qui lève une exception ou est rejeté avant de l’appeler fait échouer cette mise à jour immédiatement. Renvoie la fonction de désabonnement.
ShippingAddressChangeEvent

onShippingOptionChange

L’acheteur a choisi une option de livraison, ou Apple Pay a ré-annoncé l’option sélectionnée : une fois que tous les changements d’adresse ont reçu une réponse et qu’aucun n’est en attente, Apple Pay le déclenche pour l’option toujours sélectionnée. Il ne se déclenche jamais après une réponse qui retire l’option sélectionnée, ce qui fait de la première option la sélection sans événement ; chaque total que vous renvoyez tarifie donc l’option sélectionnée : la première jusqu’à ce que l’acheteur en choisisse une autre, l’option choisie tant que vos réponses conservent son id, et de nouveau la première dès qu’une réponse la retire. Contrat limité au montant : updateWith transporte amount/lineItems/shippingOptions/errors. Une réponse avec errors refuse l’option jusqu’à ce que l’acheteur en choisisse une que votre gestionnaire accepte. Apple Pay n’a pas d’emplacement d’erreur pour une option de livraison : il conserve donc le dernier total accepté, quoi que contienne la réponse par ailleurs, et le message de la première erreur s’affiche lorsque l’acheteur appuie sur Pay. Google Pay affiche le message lorsque l’option est choisie. Sur Apple Pay, Google Pay et PayPal, un gestionnaire qui n’a pas répondu dans les 25 secondes refuse l’option, comme le ferait un gestionnaire qui lève une exception, et sa réponse ultérieure est ignorée. Appelez updateWith(…) exactement une fois par événement. Un gestionnaire qui lève une exception ou est rejeté avant de l’appeler fait échouer cette mise à jour immédiatement. Renvoie la fonction de désabonnement.
ShippingOptionChangeEvent

onBillingAddressChange

L’acheteur a sélectionné une carte, avec son adresse de facturation masquée (ville, état, code postal et pays uniquement) : recalculez le total pour l’adresse sur laquelle le débit est taxé. Apple Pay le déclenche lorsque l’acheteur sélectionne une carte, et Google Pay à l’ouverture de la feuille puis chaque fois que l’acheteur change de carte. Répondez updateWith({ amount }) en unités mineures, updateWith({}) pour conserver le total actuel, ou updateWith({ errors }) pour refuser la carte. Chaque événement reçoit exactement une réponse : un gestionnaire qui lève une exception, est rejeté ou ne répond pas dans les 10 secondes refuse la carte, et l’acheteur en choisit donc une autre. Sur Apple Pay et Google Pay, la même sélection déclenche ensuite paymentMethodChange, et la feuille se met à jour une fois que les deux ont reçu une réponse. PayPal le déclenche avec chaque adresse de livraison choisie par l’acheteur dans PayPal, qui est l’adresse sur laquelle son jeton facture et taxe, et un refus y refuse cette adresse dans PayPal. Appelez updateWith(…) exactement une fois par événement. Un gestionnaire qui lève une exception ou est rejeté avant de l’appeler fait échouer cette mise à jour immédiatement. Renvoie la fonction de désabonnement.
BillingAddressChangeEvent

onPaymentMethodChange

L’acheteur a sélectionné un moyen de paiement : recalculez le total en conséquence, par exemple avec une majoration sur les cartes de crédit. Apple Pay le déclenche lorsque l’acheteur sélectionne une carte, et Google Pay à l’ouverture de la feuille puis chaque fois que l’acheteur change de carte, à chaque fois juste après le billingAddressChange de cette carte. paymentMethod.type vaut card. paymentMethod.card contient ce que le wallet indique d’une carte avant que l’acheteur n’autorise le paiement : Apple Pay signale son funding (Apple retient généralement le réseau jusque-là), et Google Pay son network. paymentMethod.billingAddress est l’adresse de facturation masquée de la carte. Répondez updateWith({ amount, lineItems }) pour recalculer le prix, updateWith({}) pour conserver le total actuel, ou updateWith({ errors }) pour refuser le moyen ; shippingOptions est ignoré. Apple Pay signale un refus sur le contact de facturation de la carte (sur le field nommé lorsqu’il est fourni) et bloque son bouton Pay jusqu’à ce que l’acheteur choisisse un autre moyen. Google Pay affiche le message sur la carte et refuse tout appui sur Pay avec celle-ci jusqu’à ce que l’acheteur choisisse une carte que vous acceptez. Une carte refusée laisse les totaux tels qu’ils étaient, quel que soit le prix fixé par cette réponse ou par sa réponse à billingAddressChange. Chaque événement reçoit exactement une réponse : un gestionnaire qui lève une exception, est rejeté ou ne répond pas dans les 10 secondes refuse le moyen. Chaque feuille attend votre réponse avant que l’acheteur puisse payer. PayPal ne le déclenche jamais. Appelez updateWith(…) exactement une fois par événement. Un gestionnaire qui lève une exception ou est rejeté avant de l’appeler fait échouer cette mise à jour immédiatement. Renvoie la fonction de désabonnement.
PaymentMethodChangeEvent

onPromoCodeChange

L’acheteur a saisi, modifié ou supprimé un code dans le champ promo de la feuille (requestPromoCode). Répondez updateWith({ amount }) pour appliquer le code avec un nouveau total, updateWith({}) pour l’appliquer au total actuel, ou updateWith({ error }) pour le refuser sur place. Une suppression arrive avec code à null et reçoit une réponse de la même manière. Le remplacement d’un code appliqué arrive sous la forme d’un seul événement avec le nouveau code, jamais précédé d’une suppression, et un nouveau code refusé laisse le code appliqué en place. Lorsque shippingOptions retire l’option sélectionnée, la première devient la sélection sans onShippingOptionChange, tarifez donc celle-ci. appliedDescription légende le code dans Google Pay ; le champ de coupon d’Apple Pay n’a pas de légende, placez donc tout ce que l’acheteur doit voir dans le libellé d’une ligne d’article. Un gestionnaire qui lève une exception, est rejeté ou ne répond pas dans les 10 secondes refuse le code. Appelez updateWith(…) exactement une fois par événement. Un gestionnaire qui lève une exception ou est rejeté avant de l’appeler fait échouer cette mise à jour immédiatement. Renvoie la fonction de désabonnement.
PromoCodeChangeEvent

onPaymentAuthorization

L’acheteur a autorisé le paiement, et aucun jeton de confirmation n’existe encore. Abonnez-vous pour l’approuver ou le refuser au préalable : la feuille attend votre réponse, et sans gestionnaire le jeton est créé immédiatement. L’événement contient le payeur, le moyen de paiement (avec son adresse de facturation masquée et, dans displayName, le libellé propre au wallet, comme Visa 1234), l’adresse et l’option de livraison, ainsi que le total et les lignes d’articles autorisés par l’acheteur. Répondez respondWith({ approved: true }) pour créer le jeton, que show() et onConfirmationToken fournissent ensuite comme d’habitude. Répondez respondWith({ approved: false, message }) pour refuser : aucun jeton n’est créé, Apple Pay et Google Pay affichent message dans la feuille, et l’acheteur peut modifier quelque chose et payer à nouveau, ou fermer la feuille. PayPal ne peut pas afficher votre message, donc un refus y met fin à la tentative : show() est rejeté avec payment_request_refused, et l’acheteur peut appuyer de nouveau sur PayPal. Chaque événement reçoit exactement une réponse, et seul approved: true crée un jeton : un gestionnaire qui lève une exception, est rejeté ou ne répond pas dans les 25 secondes refuse le paiement, suffisamment tôt pour qu’Apple Pay et Google Pay affichent le refus avant leur propre limite de 30 secondes. Appelez respondWith(…) exactement une fois par événement. Un gestionnaire qui lève une exception ou est rejeté avant de l’appeler fait échouer cette mise à jour immédiatement. Renvoie la fonction de désabonnement.
PaymentAuthorizationEvent

onConfirmationToken

La feuille a créé un jeton de confirmation, reçu une fois la feuille fermée. Il s’agit du même résultat que celui renvoyé par show(). Renvoie la fonction de désabonnement.
PaymentRequestResult

onCancel

L’acheteur a fermé la feuille ou PayPal. Renvoie la fonction de désabonnement.

Content Security Policy

Cette ressource 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".
Sur iOS, il s’agit uniquement d’Apple Pay : Google Pay est un parcours web show(type) sans équivalent Swift. Ni élément ni contrôleur : un objet que vous pilotez vous-même, pour un bouton d’express checkout au-dessus du formulaire. canMakePayment() prépare la feuille, et show() se résout avec le même ctok_ que celui généré par un élément. La feuille se ferme avec une coche de réussite dès que le client autorise le paiement ; confirmez le jeton sur votre serveur et affichez le résultat dans votre application.

Utilisation

Paramètres

String
requis
Le compte auquel appartient le débit, préfixé par biz_.
WhopElementsConfiguration
environment, returnURL et locale se comportent comme partout ailleurs. Par défaut : WhopElementsConfiguration().
WhopCharge
requis
.plan(id:) ou .amount(minorUnits:currency:). Peut être défini plus tard ; le prochain canMakePayment() le résout à nouveau.
WhopSetupFutureUsage?
.offSession ou .onSession. À définir uniquement après avoir affiché le consentement à l’enregistrement.
WhopPaymentRequest.Options
requestPayerEmail et requestBillingAddress demandent à la feuille ce que vous n’avez pas fourni (les deux valent true par défaut), et label remplace la ligne d’article affichée au-dessus du total.

WhopConfirmationToken

Ce que renvoie une sélection :
  • id: String : le ctok_ à confirmer côté serveur
  • paymentMethodType: WhopPaymentMethodType : apple_pay sur ce parcours

États

canMakePayment() renvoie false lorsque l’appareil ne peut pas payer, lorsque le compte n’a aucun marchand Apple Pay enregistré, ou lorsque le débit ne peut pas être résolu ; lastError indique lequel. isPresenting vaut true depuis show() jusqu’à ce qu’il renvoie un résultat ou lève une exception, y compris pendant la génération du jeton après la fermeture de la feuille ; un second show() alors qu’un autre est en cours lève confirmationInFlight. show() lève walletUnavailable plutôt que d’échouer silencieusement, et son message distingue un acheteur qui a fermé la feuille d’une feuille qui n’a pas pu s’ouvrir du tout ; une validation marchand refusée par l’API lève cette erreur d’API telle quelle.

Bon à savoir

  • show() est un simple appel asynchrone : vous pouvez donc attendre tout ce dont le débit a besoin avant de présenter la feuille.
  • Associez-le à WhopApplePayButton, qui est le PKPaymentButton d’Apple lui-même. Les directives d’Apple exigent le contrôle système plutôt qu’une imitation dessinée.
  • La feuille demande un e-mail et une adresse de facturation uniquement lorsque vous ne les avez pas fournis, et ses réponses ne comblent que les manques.
  • Le marchand Apple Pay est celui enregistré sur le compte Whop. Votre application ne fournit rien et n’a besoin d’aucune capacité In-App Payments.

Installation

WhopPaymentRequest ne nécessite ni scope ni élément monté : c’est donc la seule surface de paiement qui n’exige pas WhopBrandingElement à l’écran. Affichez vous-même la mention du marchand officiel (merchant of record). Le module est Elements, et non WhopElements du SDK wallet. Consultez Premiers pas.