Skip to main content
Deze pagina documenteert @whop/elements@1.10.0 en @whop/elements-react@1.10.0.
Sinds v1.0.0.
Maak deze Payments-resource aan zonder een element te mounten: whop.payments.paymentRequest.create({ … }) in vanilla of useWhop().payments.paymentRequest.create({ … }) in React.

Opties

Geef deze mee aan whop.payments.paymentRequest.create({ … }).
string
vereist
Account-ID, met het voorvoegsel biz_, waarbinnen elke client-side aanroep valt.
string
vereist
Drieletterige ISO 4217-code voor de betalingsvaluta.
number
vereist
Betalingsbedrag in de kleinste munteenheid. Wijzig het later met update().
"off_session" | "on_session"
Stel dit alleen in nadat je toestemming voor opslaan hebt getoond. Markeert het token voor off_session- of on_session-gebruik.
PaymentMethodConfigurationShape
Betaalmethodefilters in het formaat enabled, disabled en include_platform_defaults van de API. Ze beperken de wallets die canMakePayment() meldt: disabled verwijdert typen, enabled herstelt aangeboden typen en include_platform_defaults: false laat alleen ingeschakelde typen over. Ze voegen nooit een methode toe die het account niet aanbiedt. PayPal volgt het type paypal. Sinds v1.9.0.
boolean
Vraag de sheet om het e-mailadres van de betaler — het bevestigingstoken vereist er een. Standaard true.
boolean
Vraag de sheet om het telefoonnummer van de betaler, geleverd als payer.phone in het resultaat — in E.164 als het kan worden geparset op basis van het land van het contact dat het heeft opgegeven, en anders zoals de wallet het gaf; payer.country is het factuurland. Google Pay verzamelt het via het factuuradres waar de sheet al om vraagt. PayPal verzamelt het via de contactsectie en weigert een account zonder telefoonnummer. Standaard false.
boolean
Vraag de sheet om een verzendadres (en bied shippingOptions aan als die zijn opgegeven). PayPal vraagt altijd om een adres, omdat daarover de belasting wordt berekend, en retourneert het alleen als shipping wanneer dit is ingesteld. Standaard false.
boolean
Bied het eigen promotiecodeveld van de sheet aan en beantwoord onPromoCodeChange. Apple Pay toont het veld op apparaten die Apple Pay versie 12 ondersteunen (iOS 15 en macOS 12); Google Pay toont het waar de Google Pay-configuratie van het account aanbiedingen toestaat. Andere apparaten openen de sheet zonder het veld. Standaard false. Sinds v1.5.0.
string
Een promotiecode die al op de afschrijving is toegepast, vooraf ingevuld in de sheet zodat de koper die kan zien, vervangen of verwijderen. Sinds v1.5.0.
string
Wat appliedPromoCode doet, getoond naast de code in Google Pay. Het couponveld van Apple Pay heeft geen bijschrift. Sinds v1.5.0.
string
ISO 3166-1 alpha-2-landcode van het account voor de Apple Pay-sheet. Laat het weg om het gepubliceerde registratieland van het account te gebruiken. De sheet gebruikt standaard US wanneer geen van beide beschikbaar is.
PaymentRequestLineItem[]
Regelitems die de sheet onder het totaal vermeldt. Wijzig ze later met update().
PaymentRequestShippingOption[]
Verzendopties die de sheet aanbiedt wanneer requestShipping is ingesteld. Alleen voor weergave — werk amount bij vanuit je change-handler. De sheet opent met de eerste optie geselecteerd en activeert daarvoor geen onShippingOptionChange, dus amount moet de prijs ervan al bevatten. Wijzig ze later met update().

Methoden

Roep deze aan op de resource.
Roep show synchroon aan tijdens gebruikersactivatie. Wacht eerst op vereisten.

canMakePayment

Retourneert de beschikbaarheid van elke wallet wanneer het account die aanbiedt, het apparaat die ondersteunt en de origin van deze pagina voor het account is goedgekeurd (first-party whop.com-pagina’s zijn vooraf goedgekeurd; een merchantpagina heeft Apple Pay nodig die op het domein gereed is via de Domains API, en het aanbieden van Google Pay daar valt onder de Google Pay API Terms of Service). Op een pagina die zelf in een iframe staat, controleert Apple Pay in plaats daarvan het domein van de pagina op het hoogste niveau wanneer de browser dat beschikbaar stelt. Apple Pay in niet-WebKit-browsers is de desktopflow met overdracht naar de iPhone, dus mobiele apparaten melden het daar als niet beschikbaar — native Apple Pay in iOS-browsers wordt niet beïnvloed. order rangschikt de wallets op welke sheet native is in de browser — Apple Pay eerst in Safari, Google Pay eerst elders, PayPal als laatste — zodat expressknoppen met de beste bovenaan kunnen worden gestapeld. payPal meldt PayPal wanneer het account het in deze valuta aanbiedt, het bedrag binnen de limieten van PayPal valt, het verzoek niet om het telefoonnummer van de betaler vraagt (een off_session-verzoek mag $0 zijn, wat PayPal opslaat zonder afschrijving), de scripts van PayPal op deze pagina laden en de origin van deze pagina voor het account is goedgekeurd, net als bij de andere wallets. Een pagina met een Content Security Policy moet de hosts van PayPal toestaan, die contentSecurityPolicy() bevat. Een pagina die de eigen v5 JavaScript SDK van PayPal al laadt, meldt payPal: false. Geef types mee om alleen de wallets te controleren die je opgeeft; show(type) vereist dat die wallet is gecontroleerd. wallets bevat de officiële knopafbeelding van elke beschikbare wallet (light en dark kleur en afbeelding). Dit bereidt show() voor. Wacht hier altijd eerst op.Parameters
object
Retourneert Promise<WalletAvailability>
boolean
vereist
boolean
vereist
boolean
("apple_pay" | "google_pay" | "paypal_express")[]
De wallets gerangschikt op welke sheet native is in deze browser — Apple Pay eerst op WebKit, Google Pay eerst overal elders, PayPal als laatste — zodat expressknoppen met de beste bovenaan kunnen worden gestapeld. Ontbreekt bij door de consument opgegeven beschikbaarheid (previews) en bij berichten van vóór deze toevoeging. Een inline union, niet de WalletSheetType van payment-request: die module importeert deze al.
object
De details van elke beschikbare wallet, met het wallettype als sleutel. Ontbreekt bij door de consument opgegeven beschikbaarheid (previews).

show

Open de geselecteerde wallet nadat je op canMakePayment() hebt gewacht, synchroon bij het indrukken: Apple vereist dat de sessie binnen de gebarenstack wordt aangemaakt, en PayPal opent daar zijn venster — een pop-up op desktop, het venster van PayPal op de pagina wanneer de pop-up wordt geblokkeerd en op mobiel. Geef email mee wanneer je pagina er al een heeft verzameld — de wallet neemt het over en vraagt nooit om een tweede. Met requestPayerEmail: false is het verplicht er een mee te geven, en weigert de wallet zonder te openen omdat bevestigingstokens een e-mailadres vereisen. Zolang de sheet open is, gooit update() een fout: beantwoord de change-events om de sheet te wijzigen. Roep het synchroon aan tijdens gebruikersactivering. Wacht eerst op vereisten, omdat browsers de activering intrekken over asynchrone stappen heen.Parameters
"apple_pay" | "google_pay" | "paypal_express"
vereist
object
Retourneert Promise<PaymentRequestResult>
string
vereist
ID van het bevestigingstoken, met het voorvoegsel ctok_. Bevestig het server-side met je geheime sleutel.
"apple_pay" | "google_pay" | "paypal_express"
vereist
object
vereist
phone is E.164 als het kon worden geparset op basis van het land van het contact, en anders zoals opgegeven; PayPal geeft er alleen een bij requestPayerPhone en weigert een account zonder telefoonnummer. country is het factuurland dat elke sheet verzamelt.
object | null
vereist
Het volledige factuuradres dat het bevestigingstoken meedraagt, anders dan het afgeschermde adres in de change-events; null wanneer de wallet er geen gaf. Apple Pay en Google Pay geven het factuuradres van de kaart. Bij PayPal is het het adres dat de koper in PayPal heeft gekozen, waarover het totaal is belast.
object | null
vereist
null tenzij requestShipping is ingesteld. option is de geselecteerde verzendoptie: de eerst aangeboden optie totdat de koper een andere kiest, en opnieuw de eerste wanneer een antwoord de opties heeft vervangen zonder de gekozen id. Apple Pay en Google Pay stellen het in wanneer er opties zijn aangeboden, PayPal nooit.

update

Wijzig amount, lineItems en shippingOptions op deze instantie. Elke andere optie ligt vast bij create(): maak een nieuwe instantie aan om die te wijzigen.Parameters
object
vereist

Events

Abonneer je hieronder op events. Elke methode retourneert een functie om het abonnement op te zeggen.
Elke event-handler moet de gedocumenteerde antwoordmethode precies één keer aanroepen. Een handler die een fout gooit of wordt afgewezen voordat die antwoordt, laat die update direct mislukken.

onShippingAddressChange

De koper heeft een verzendadres gekozen (vóór autorisatie afgeschermd: alleen plaats, staat, postcode en land; Apple Pay kort een Amerikaanse ZIP-code in tot vijf cijfers en laat de laatste drie tekens van een Canadese of Britse postcode weg). Antwoord met de totalen voor het adres en de geselecteerde verzendoptie: de eerste totdat de koper een andere kiest. shippingOptions vervangt de opties (een lege lijst verandert niets). Een gekozen optie blijft geselecteerd zolang het antwoord de id ervan behoudt; als het antwoord die weglaat, wordt de eerste optie de selectie zonder een onShippingOptionChange, dus prijs die. Elke fout in het antwoord blijft op het adres staan totdat een later antwoord voor een adres die wist: een fout die een field noemt (city, state, postal_code, country) markeert dat veld in Apple Pay, en Google Pay toont alleen de melding. Betalen wordt geweigerd zolang er een fout op het adres staat. Weiger een adres waarnaar je niet kunt verzenden met een shipping_address_unserviceable-fout zonder field. Bij Apple Pay, Google Pay en PayPal laat een handler die niet binnen 25 seconden heeft geantwoord het adres mislukken, net als een handler die een fout gooit, en wordt het latere antwoord genegeerd. PayPal activeert het met het adres dat de koper kiest, en een fout die een field noemt, weigert dat deel van het adres binnen PayPal. Roep updateWith(…) precies één keer per event aan. Een handler die een fout gooit of wordt geweigerd voordat hij het aanroept, laat die update meteen mislukken. Retourneert de functie om het abonnement op te zeggen.
ShippingAddressChangeEvent

onShippingOptionChange

De koper heeft een verzendoptie gekozen, of Apple Pay heeft de geselecteerde opnieuw gemeld: zodra alle adreswijzigingen zijn beantwoord en er geen meer wacht, activeert Apple Pay het voor de optie die nog geselecteerd is. Het wordt nooit geactiveerd na een antwoord dat de geselecteerde optie weglaat, waardoor de eerste optie zonder event de selectie wordt, dus elk totaal dat je antwoordt, prijst de geselecteerde optie: de eerste totdat de koper een andere kiest, de gekozen optie zolang je antwoorden de id ervan behouden, en opnieuw de eerste zodra een antwoord die weglaat. Contract alleen voor bedragen: updateWith bevat amount/lineItems/shippingOptions/errors. Een antwoord met errors weigert de optie totdat de koper er een kiest die je handler accepteert. Apple Pay heeft geen foutplek voor een verzendoptie, dus het behoudt het laatst geaccepteerde totaal, wat het antwoord verder ook bevat, en de melding van de eerste fout verschijnt wanneer de koper op Pay tikt. Google Pay toont de melding wanneer de optie wordt gekozen. Bij Apple Pay, Google Pay en PayPal weigert een handler die niet binnen 25 seconden heeft geantwoord de optie, net als een handler die een fout gooit, en wordt het latere antwoord genegeerd. Roep updateWith(…) precies één keer per event aan. Een handler die een fout gooit of wordt geweigerd voordat hij het aanroept, laat die update meteen mislukken. Retourneert de functie om het abonnement op te zeggen.
ShippingOptionChangeEvent

onBillingAddressChange

De koper heeft een kaart geselecteerd, met het afgeschermde factuuradres (alleen plaats, staat, postcode en land): prijs het totaal opnieuw voor het adres waarover de afschrijving wordt belast. Apple Pay activeert het wanneer de koper een kaart selecteert, en Google Pay wanneer de sheet opent en telkens wanneer de koper van kaart wisselt. Antwoord met updateWith({ amount }) in de kleinste munteenheid, updateWith({}) om het huidige totaal te behouden, of updateWith({ errors }) om de kaart te weigeren. Elk event wordt precies één keer beantwoord: een handler die een fout gooit, wordt geweigerd of niet binnen 10 seconden antwoordt, weigert de kaart, zodat de koper een andere kiest. Bij Apple Pay en Google Pay activeert dezelfde selectie daarna paymentMethodChange, en de sheet wordt bijgewerkt zodra beide zijn beantwoord. PayPal activeert het met elk verzendadres dat de koper in PayPal kiest, het adres waarop het token factureert en belast, en een weigering daar weigert dat adres binnen PayPal. Roep updateWith(…) precies één keer per event aan. Een handler die een fout gooit of wordt geweigerd voordat hij het aanroept, laat die update meteen mislukken. Retourneert de functie om het abonnement op te zeggen.
BillingAddressChangeEvent

onPaymentMethodChange

De koper heeft een betaalmethode geselecteerd: prijs het totaal daarvoor opnieuw, bijvoorbeeld met een toeslag op creditcards. Apple Pay activeert het wanneer de koper een kaart selecteert, en Google Pay wanneer de sheet opent en telkens wanneer de koper van kaart wisselt, steeds direct na de billingAddressChange van die kaart. paymentMethod.type is card. paymentMethod.card bevat wat de wallet over een kaart vertelt voordat de koper autoriseert: Apple Pay meldt de funding (Apple houdt het netwerk tot dan meestal achter), en Google Pay het network. paymentMethod.billingAddress is het afgeschermde factuuradres van de kaart. Antwoord met updateWith({ amount, lineItems }) om opnieuw te prijzen, updateWith({}) om het huidige totaal te behouden, of updateWith({ errors }) om de methode te weigeren; shippingOptions wordt genegeerd. Apple Pay markeert een weigering op het factuurcontact van de kaart (op het genoemde field als dat is opgegeven) en houdt de Pay-knop tegen totdat de koper een andere methode kiest. Google Pay toont de melding op de kaart en weigert een tik op Pay daarvoor totdat de koper een kaart kiest die je accepteert. Een geweigerde kaart laat de totalen zoals ze waren, wat dit antwoord of het antwoord op de billingAddressChange ervan ook prijsde. Elk event wordt precies één keer beantwoord: een handler die een fout gooit, wordt geweigerd of niet binnen 10 seconden antwoordt, weigert de methode. Elke sheet wacht op je antwoord voordat de koper kan betalen. PayPal activeert het nooit. Roep updateWith(…) precies één keer per event aan. Een handler die een fout gooit of wordt geweigerd voordat hij het aanroept, laat die update meteen mislukken. Retourneert de functie om het abonnement op te zeggen.
PaymentMethodChangeEvent

onPromoCodeChange

De koper heeft een code getypt, gewijzigd of verwijderd in het promotieveld van de sheet (requestPromoCode). Antwoord met updateWith({ amount }) om de code toe te passen tegen een nieuw totaal, updateWith({}) om die toe te passen tegen het huidige totaal, of updateWith({ error }) om die ter plekke te weigeren. Een verwijdering komt binnen met code null en wordt op dezelfde manier beantwoord. Het vervangen van een toegepaste code komt binnen als één event met de nieuwe code, nooit eerst een verwijdering, en een geweigerde nieuwe code laat de toegepaste staan. Wanneer shippingOptions de geselecteerde optie weglaat, wordt de eerste de selectie zonder een onShippingOptionChange, dus prijs die. appliedDescription geeft de code een bijschrift in Google Pay; het couponveld van Apple Pay heeft geen bijschrift, dus zet alles wat de koper moet zien in het label van een regelitem. Een handler die een fout gooit, wordt geweigerd of niet binnen 10 seconden antwoordt, weigert de code. Roep updateWith(…) precies één keer per event aan. Een handler die een fout gooit of wordt geweigerd voordat hij het aanroept, laat die update meteen mislukken. Retourneert de functie om het abonnement op te zeggen.
PromoCodeChangeEvent

onPaymentAuthorization

De koper heeft de betaling geautoriseerd en er bestaat nog geen bevestigingstoken. Abonneer je om de betaling eerst goed te keuren of te weigeren: de sheet wacht op je antwoord, en zonder handler wordt het token direct aangemaakt. Het event bevat de betaler, de betaalmethode (met het afgeschermde factuuradres, en in displayName het eigen label van de wallet ervoor, zoals Visa 1234), het verzendadres en de verzendoptie, en het totaal en de regelitems die de koper heeft geautoriseerd. Antwoord met respondWith({ approved: true }) om het token aan te maken, dat show() en onConfirmationToken daarna zoals gebruikelijk leveren. Antwoord met respondWith({ approved: false, message }) om te weigeren: er wordt geen token aangemaakt, Apple Pay en Google Pay tonen message in de sheet, en de koper kan iets wijzigen en opnieuw betalen, of de sheet sluiten. PayPal kan je melding niet tonen, dus een weigering daar beëindigt de poging: show() wordt geweigerd met payment_request_refused, en de koper kan opnieuw op PayPal drukken. Elk event wordt precies één keer beantwoord, en alleen approved: true maakt een token aan: een handler die een fout gooit, wordt geweigerd of niet binnen 25 seconden antwoordt, weigert de betaling, vroeg genoeg voor Apple Pay en Google Pay om de weigering te tonen vóór hun eigen limiet van 30 seconden. Roep respondWith(…) precies één keer per event aan. Een handler die een fout gooit of wordt geweigerd voordat hij het aanroept, laat die update meteen mislukken. Retourneert de functie om het abonnement op te zeggen.
PaymentAuthorizationEvent

onConfirmationToken

De sheet heeft een bevestigingstoken aangemaakt, ontvangen zodra de sheet is gesloten. Dit is hetzelfde resultaat dat show() retourneert. Retourneert de functie om het abonnement op te zeggen.
PaymentRequestResult

onCancel

De koper heeft de sheet gesloten of PayPal gesloten. Retourneert de functie om het abonnement op te zeggen.

Content Security Policy

Deze resource wordt uitgevoerd op je pagina, niet in een frame. Een pagina met een Content Security Policy heeft deze bronnen nodig. contentSecurityPolicy() uit @whop/elements retourneert elke bron in deze tabel. De sandboxbron geldt bij environment: "sandbox".
Op iOS is dit alleen Apple Pay: Google Pay is een show(type)-route voor het web zonder Swift-tegenhanger. Geen element en geen controller: een object dat je zelf aanstuurt, voor een express-checkoutknop boven het formulier. canMakePayment() bereidt de sheet voor, en show() levert hetzelfde ctok_ op dat een element aanmaakt. De sheet sluit met een succesvinkje zodra de klant autoriseert; bevestig het token op je server en toon de uitkomst in je app.

Gebruik

Parameters

String
vereist
Het account waartoe de afschrijving behoort, met het voorvoegsel biz_.
WhopElementsConfiguration
environment, returnURL en locale werken zoals overal elders. Standaard WhopElementsConfiguration().
WhopCharge
vereist
.plan(id:) of .amount(minorUnits:currency:). Kan later worden ingesteld; de volgende canMakePayment() haalt het opnieuw op.
WhopSetupFutureUsage?
.offSession of .onSession. Stel dit alleen in nadat je toestemming voor opslaan hebt getoond.
WhopPaymentRequest.Options
requestPayerEmail en requestBillingAddress vragen de sheet om wat je niet hebt aangeleverd (beide standaard true), en label overschrijft het regelitem dat boven het totaal wordt getoond.

WhopConfirmationToken

Wat een selectie teruggeeft:
  • id: String: de ctok_ die server-side moet worden bevestigd
  • paymentMethodType: WhopPaymentMethodType: apple_pay op deze route

Statussen

canMakePayment() retourneert false wanneer het apparaat niet kan betalen, wanneer het account geen geregistreerde Apple Pay-merchant heeft, of wanneer de afschrijving niet kan worden opgehaald; lastError vertelt welke. isPresenting is true vanaf show() totdat die retourneert of een fout gooit, inclusief het aanmaken van het token nadat de sheet is gesloten; een tweede show() terwijl er een bezig is, gooit confirmationInFlight. show() gooit walletUnavailable in plaats van geruisloos te mislukken, en de melding maakt onderscheid tussen een koper die de sheet heeft gesloten en een sheet die helemaal niet kon openen; een merchantvalidatie die de API weigert, gooit die API-fout zoals ontvangen.

Goed om te weten

  • show() is een gewone async-aanroep, dus je kunt wachten op wat de afschrijving nodig heeft voordat je de sheet toont.
  • Combineer het met WhopApplePayButton, de eigen PKPaymentButton van Apple. De richtlijnen van Apple vereisen het systeembedieningselement in plaats van een getekende imitatie.
  • De sheet wordt precies dan om een e-mailadres en factuuradres gevraagd wanneer je die niet hebt aangeleverd, en de antwoorden vullen alleen de gaten.
  • De Apple Pay-merchant is degene die op het Whop-account is geregistreerd. Je app levert niets aan en heeft geen In-App Payments-capability nodig.

Installatie

WhopPaymentRequest heeft geen scope en geen gemount element nodig, dus het is het enige betaaloppervlak waarvoor WhopBrandingElement niet op het scherm hoeft te staan. Toon de merchant-of-record-regel zelf. De module is Elements, niet WhopElements van de wallet-SDK. Zie Aan de slag.