Skip to main content
Denne side dokumenterer @whop/elements@1.10.0 og @whop/elements-react@1.10.0.
Siden v1.0.0.
Opret denne Payments-ressource uden at montere et element: whop.payments.paymentRequest.create({ … }) i vanilla eller useWhop().payments.paymentRequest.create({ … }) i React.

Indstillinger

Angiv disse til whop.payments.paymentRequest.create({ … }).
string
påkrævet
Konto-ID med præfikset biz_, som afgrænser alle kald på klientsiden.
string
påkrævet
Valutakode på tre bogstaver efter ISO 4217 for betalingen.
number
påkrævet
Betalingsbeløb i mindste valutaenhed. Ændr det senere med update().
"off_session" | "on_session"
Sæt kun, efter at du har vist samtykke til at gemme. Markerer tokenet til brug med off_session eller on_session.
PaymentMethodConfigurationShape
Filtre for betalingsmetoder i API’ets format med enabled, disabled og include_platform_defaults. De indsnævrer de wallets, som canMakePayment() rapporterer: disabled fjerner typer, enabled gendanner tilbudte typer, og include_platform_defaults: false efterlader kun aktiverede typer. De tilføjer aldrig en metode, som kontoen ikke tilbyder. PayPal følger typen paypal. Siden v1.9.0.
boolean
Bed arket om betalerens e-mail — bekræftelsestokenet kræver en. Standard er true.
boolean
Bed arket om betalerens telefonnummer, leveret som payer.phone i resultatet — i E.164, hvor det kan fortolkes ud fra landet for den kontakt, der angav det, og ellers som wallet’en gav det; payer.country er faktureringslandet. Google Pay indsamler det via den faktureringsadresse, arket allerede beder om. PayPal indsamler det via sin kontaktsektion og afviser en konto uden et. Standard er false.
boolean
Bed arket om en leveringsadresse (og tilbyd shippingOptions, når de er angivet). PayPal beder altid om en adresse, da det er den adresse, momsen beregnes ud fra, og returnerer den kun som shipping, når denne er sat. Standard er false.
boolean
Tilbyd arkets eget felt til rabatkode, og besvar onPromoCodeChange. Apple Pay viser feltet på enheder, der understøtter Apple Pay version 12 (iOS 15 og macOS 12); Google Pay viser det, hvor kontoens Google Pay-opsætning tillader tilbud. Andre enheder åbner arket uden det. Standard er false. Siden v1.5.0.
string
En rabatkode, der allerede er anvendt på opkrævningen, forudfyldt i arket, så køberen kan se, erstatte eller fjerne den. Siden v1.5.0.
string
Hvad appliedPromoCode gør, vist ved siden af koden i Google Pay. Apple Pays kuponfelt har ingen billedtekst. Siden v1.5.0.
string
Kontoens landekode efter ISO 3166-1 alpha-2 til Apple Pay-arket. Udelad den for at bruge kontoens offentliggjorte registreringsland. Arket bruger som standard US, når ingen af dem er tilgængelige.
PaymentRequestLineItem[]
Linjeposter, som arket viser under totalen. Ændr dem senere med update().
PaymentRequestShippingOption[]
Forsendelsesmuligheder, som arket tilbyder, når requestShipping er sat. Kun til visning — opdater amount fra din change-handler. Arket åbner med den første mulighed valgt og udløser ingen onShippingOptionChange for den, så amount skal allerede indeholde dens pris. Ændr dem senere med update().

Metoder

Kald disse på ressourcen.
Kald show synkront under brugeraktivering. Afvent forudsætningerne først.

canMakePayment

Returnerer tilgængeligheden for hver wallet, når kontoen tilbyder den, enheden understøtter den, og denne sides origin er godkendt for kontoen (førstepartssider på whop.com er forhåndsgodkendt; en forhandlerside skal have Apple Pay klar på sit domæne via Domains API, og at tilbyde Google Pay dér er underlagt Google Pay API Terms of Service). På en side, der selv ligger i en iframe, kontrollerer Apple Pay i stedet domænet for siden på øverste niveau, når browseren eksponerer det. Apple Pay i browsere, der ikke er WebKit, er desktop-flowet med overdragelse til iPhone, så mobile enheder dér rapporterer det som utilgængeligt — native Apple Pay i iOS-browsere påvirkes ikke. order rangerer wallets efter, hvilket ark der er native i browseren — Apple Pay først i Safari, Google Pay først andre steder, PayPal sidst — så express-knapper kan stables med den bedste først. payPal rapporterer PayPal, hvor kontoen tilbyder det i denne valuta, beløbet ligger inden for PayPals grænser, anmodningen ikke beder om betalerens telefonnummer (en off_session-anmodning må være $0, hvilket gemmer PayPal uden en opkrævning), PayPals scripts indlæses på denne side, og denne sides origin er godkendt for kontoen ligesom for de andre wallets. En side med en Content Security Policy skal tillade PayPals hosts, som contentSecurityPolicy() medtager. En side, der allerede indlæser PayPals egen v5 JavaScript SDK, rapporterer payPal: false. Angiv types for kun at kontrollere de wallets, du angiver; show(type) kræver, at den pågældende wallet er kontrolleret. wallets indeholder hver tilgængelig wallets officielle knapgrafik (light- og dark-farve og -billede). Dette forbereder show(). Afvent det altid først.Parametre
object
Returnerer Promise<WalletAvailability>
boolean
påkrævet
boolean
påkrævet
boolean
("apple_pay" | "google_pay" | "paypal_express")[]
De wallets, rangeret efter hvilket ark der er native i denne browser — Apple Pay først i WebKit, Google Pay først alle andre steder, PayPal sidst — så express-knapper kan stables med den bedste først. Fraværende ved tilgængelighed angivet af forbrugeren (forhåndsvisninger) og på wire-formater, der er ældre end den. En inline-union, ikke payment-requests WalletSheetType: det modul importerer allerede dette.
object
Hver tilgængelig wallets oplysninger, nøglet efter wallet-type. Fraværende ved tilgængelighed angivet af forbrugeren (forhåndsvisninger).

show

Åbn den valgte wallet efter at have afventet canMakePayment(), synkront i trykket: Apple kræver, at sessionen oprettes inden for gestus-stakken, og PayPal åbner sit vindue dér — et pop op-vindue på desktop, PayPals vindue på siden, når pop op-vinduet blokeres, og på mobil. Angiv email, når din side allerede har indsamlet en — wallet’en tager den og spørger aldrig om en anden. Med requestPayerEmail: false er det påkrævet at angive en, og wallet’en nægter at åbne uden den, fordi bekræftelsestokens kræver en e-mail. Mens arket er åbent, kaster update() en fejl: besvar change-events for at ændre det. Kald synkront under brugeraktivering. Afvent forudsætningerne først, fordi browsere tilbagekalder aktivering på tværs af asynkrone trin.Parametre
"apple_pay" | "google_pay" | "paypal_express"
påkrævet
object
Returnerer Promise<PaymentRequestResult>
string
påkrævet
Bekræftelsestoken-ID med præfikset ctok_. Bekræft det på serversiden med din hemmelige nøgle.
"apple_pay" | "google_pay" | "paypal_express"
påkrævet
object
påkrævet
phone er i E.164, hvor det kunne fortolkes ud fra kontaktens land, og ellers som angivet; PayPal giver kun et for requestPayerPhone og afviser en konto uden et. country er det faktureringsland, som alle ark indsamler.
object | null
påkrævet
Den fulde faktureringsadresse, som bekræftelsestokenet bærer, i modsætning til den redigerede, som change-events bærer; null, når wallet’en ikke gav nogen. Apple Pay og Google Pay giver kortets faktureringsadresse. På PayPal er det den adresse, køberen valgte i PayPal, den som totalen blev momsberegnet ud fra.
object | null
påkrævet
null, medmindre requestShipping var sat. option er den valgte forsendelsesmulighed: den første tilbudte, indtil køberen vælger en anden, og igen den første, når et svar erstattede mulighederne uden det valgte id. Apple Pay og Google Pay sætter den, når der blev tilbudt muligheder, og PayPal gør det aldrig.

update

Ændr amount, lineItems og shippingOptions på denne instans. Alle andre indstillinger er fastlagt ved create(): opret en ny instans for at ændre dem.Parametre
object
påkrævet

Events

Abonnér på events nedenfor. Hver metode returnerer en afmeldingsfunktion.
Hver event-handler skal kalde sin dokumenterede svarmetode præcis én gang. En handler, der kaster en fejl eller afviser, før den svarer, får den pågældende opdatering til at mislykkes med det samme.

onShippingAddressChange

Køberen valgte en leveringsadresse (redigeret før godkendelse: kun by, stat, postnummer og land; Apple Pay afkorter et amerikansk ZIP-nummer til fem cifre og fjerner de sidste tre tegn af et canadisk eller britisk postnummer). Svar med totalerne for adressen og den valgte forsendelsesmulighed: den første, indtil køberen vælger en anden. shippingOptions erstatter mulighederne (en tom liste ændrer intet). En valgt mulighed forbliver valgt, så længe svaret bevarer dens id; når svaret udelader den, bliver den første mulighed valgt uden en onShippingOptionChange, så prissæt den. Hver fejl i svaret bliver på adressen, indtil et senere svar for en adresse rydder den: en fejl, der angiver et field (city, state, postal_code, country), markerer det felt i Apple Pay, og Google Pay viser kun beskeden. Betaling afvises, så længe der står en fejl på adressen. Afvis en adresse, du ikke kan sende til, med en shipping_address_unserviceable-fejl uden field. På Apple Pay, Google Pay og PayPal får en handler, der ikke har svaret inden for 25 sekunder, adressen til at mislykkes, ligesom en handler, der kaster en fejl, og dens senere svar ignoreres. PayPal udløser den med den adresse, køberen vælger, og en fejl, der angiver et field, afviser den del af adressen inde i PayPal. Kald updateWith(…) præcis én gang pr. event. En handler, der kaster en fejl eller afviser, før den kalder den, får den pågældende opdatering til at mislykkes med det samme. Returnerer afmeldingsfunktionen.
ShippingAddressChangeEvent

onShippingOptionChange

Køberen valgte en forsendelsesmulighed, eller Apple Pay genannoncerede den valgte: når alle adresseændringer er besvaret, og ingen venter, udløser Apple Pay den for den mulighed, der stadig er valgt. Den udløses aldrig efter et svar, der udelader den valgte mulighed, hvilket gør den første mulighed til den valgte uden en event, så hver total, du svarer med, prissætter den valgte mulighed: den første, indtil køberen vælger en anden, køberens valg, så længe dine svar bevarer dens id, og igen den første, når et svar udelader den. Kontrakt kun for beløb: updateWith indeholder amount/lineItems/shippingOptions/errors. Et svar med errors afviser muligheden, indtil køberen vælger en, som din handler accepterer. Apple Pay har ingen fejlplads til en forsendelsesmulighed, så den beholder den senest accepterede total, uanset hvad svaret ellers indeholder, og den første fejls besked vises, når køberen trykker på Pay. Google Pay viser beskeden, når muligheden vælges. På Apple Pay, Google Pay og PayPal afviser en handler, der ikke har svaret inden for 25 sekunder, muligheden, ligesom en handler, der kaster en fejl, og dens senere svar ignoreres. Kald updateWith(…) præcis én gang pr. event. En handler, der kaster en fejl eller afviser, før den kalder den, får den pågældende opdatering til at mislykkes med det samme. Returnerer afmeldingsfunktionen.
ShippingOptionChangeEvent

onBillingAddressChange

Køberen valgte et kort med dets redigerede faktureringsadresse (kun by, stat, postnummer og land): prissæt totalen igen for den adresse, opkrævningen momsberegnes ud fra. Apple Pay udløser den, når køberen vælger et kort, og Google Pay, når arket åbner, og hver gang køberen skifter kort. Svar med updateWith({ amount }) i mindste valutaenhed, updateWith({}) for at beholde den aktuelle total eller updateWith({ errors }) for at afvise kortet. Hver event besvares præcis én gang: en handler, der kaster en fejl, afviser eller ikke svarer inden for 10 sekunder, afviser kortet, så køberen vælger et andet. På Apple Pay og Google Pay udløser det samme valg derefter paymentMethodChange, og arket opdateres, når begge er besvaret. PayPal udløser den med hver leveringsadresse, køberen vælger i PayPal, hvilket er den adresse, dets token fakturerer og momsberegner ud fra, og en afvisning dér afviser den adresse inde i PayPal. Kald updateWith(…) præcis én gang pr. event. En handler, der kaster en fejl eller afviser, før den kalder den, får den pågældende opdatering til at mislykkes med det samme. Returnerer afmeldingsfunktionen.
BillingAddressChangeEvent

onPaymentMethodChange

Køberen valgte en betalingsmetode: prissæt totalen igen for den, f.eks. et tillæg på kreditkort. Apple Pay udløser den, når køberen vælger et kort, og Google Pay, når arket åbner, og hver gang køberen skifter kort, hver gang lige efter kortets billingAddressChange. paymentMethod.type er card. paymentMethod.card indeholder det, wallet’en fortæller om et kort, før køberen godkender: Apple Pay rapporterer dets funding (Apple tilbageholder normalt netværket indtil da), og Google Pay dets network. paymentMethod.billingAddress er kortets redigerede faktureringsadresse. Svar med updateWith({ amount, lineItems }) for at prissætte igen, updateWith({}) for at beholde den aktuelle total eller updateWith({ errors }) for at afvise metoden; shippingOptions ignoreres. Apple Pay markerer en afvisning på kortets faktureringskontakt (på det angivne field, når et er angivet) og holder sin Pay-knap tilbage, indtil køberen vælger en anden metode. Google Pay viser beskeden på kortet og afviser et tryk på Pay på det, indtil køberen vælger et kort, du accepterer. Et afvist kort efterlader totalerne, som de var, uanset hvad dette svar eller dets svar på billingAddressChange prissatte. Hver event besvares præcis én gang: en handler, der kaster en fejl, afviser eller ikke svarer inden for 10 sekunder, afviser metoden. Hvert ark venter på dit svar, før køberen kan betale. PayPal udløser den aldrig. Kald updateWith(…) præcis én gang pr. event. En handler, der kaster en fejl eller afviser, før den kalder den, får den pågældende opdatering til at mislykkes med det samme. Returnerer afmeldingsfunktionen.
PaymentMethodChangeEvent

onPromoCodeChange

Køberen indtastede, ændrede eller fjernede en kode i arkets felt til rabatkode (requestPromoCode). Svar med updateWith({ amount }) for at anvende koden med en ny total, updateWith({}) for at anvende den med den aktuelle total eller updateWith({ error }) for at afvise den på stedet. En fjernelse ankommer med code sat til null og besvares på samme måde. Erstatning af en anvendt kode ankommer som én event med den nye kode, aldrig en fjernelse først, og en afvist ny kode efterlader den anvendte på plads. Når shippingOptions udelader den valgte mulighed, bliver den første valgt uden en onShippingOptionChange, så prissæt den. appliedDescription giver koden en billedtekst i Google Pay; Apple Pays kuponfelt har ingen billedtekst, så skriv alt, hvad køberen skal se, i en linjepostetiket. En handler, der kaster en fejl, afviser eller ikke svarer inden for 10 sekunder, afviser koden. Kald updateWith(…) præcis én gang pr. event. En handler, der kaster en fejl eller afviser, før den kalder den, får den pågældende opdatering til at mislykkes med det samme. Returnerer afmeldingsfunktionen.
PromoCodeChangeEvent

onPaymentAuthorization

Køberen godkendte betalingen, og der findes endnu intet bekræftelsestoken. Abonnér for at godkende eller afvise den først: arket venter på dit svar, og uden en handler oprettes tokenet med det samme. Eventen indeholder betaleren, betalingsmetoden (med dens redigerede faktureringsadresse og i displayName wallet’ens egen etiket for den, f.eks. Visa 1234), leveringsadressen og -muligheden samt den total og de linjeposter, køberen godkendte. Svar med respondWith({ approved: true }) for at oprette tokenet, som show() og onConfirmationToken derefter leverer som sædvanligt. Svar med respondWith({ approved: false, message }) for at afvise: intet token oprettes, Apple Pay og Google Pay viser message i arket, og køberen kan ændre noget og betale igen eller lukke arket. PayPal kan ikke vise din besked, så en afvisning dér afslutter forsøget: show() afviser med payment_request_refused, og køberen kan trykke på PayPal igen. Hver event besvares præcis én gang, og kun approved: true opretter et token: en handler, der kaster en fejl, afviser eller ikke svarer inden for 25 sekunder, afviser betalingen tidligt nok til, at Apple Pay og Google Pay kan vise afvisningen før deres egen grænse på 30 sekunder. Kald respondWith(…) præcis én gang pr. event. En handler, der kaster en fejl eller afviser, før den kalder den, får den pågældende opdatering til at mislykkes med det samme. Returnerer afmeldingsfunktionen.
PaymentAuthorizationEvent

onConfirmationToken

Arket oprettede et bekræftelsestoken, modtaget, når arket er lukket. Dette er det samme resultat, som show() returnerer. Returnerer afmeldingsfunktionen.
PaymentRequestResult

onCancel

Køberen lukkede arket eller lukkede PayPal. Returnerer afmeldingsfunktionen.

Content Security Policy

Denne ressource kører på din side, ikke i en frame. En side med en Content Security Policy har brug for disse kilder. contentSecurityPolicy() fra @whop/elements returnerer alle kilder i denne tabel. Sandbox-kilden gælder med environment: "sandbox".
På iOS er dette kun Apple Pay: Google Pay er en web-show(type)-bane uden Swift-modstykke. Intet element og ingen controller: et objekt, du selv styrer, til en express checkout-knap over formularen. canMakePayment() forbereder arket, og show() opløses til det samme ctok_, som et element udsteder. Arket lukker med et flueben for gennemført, så snart kunden godkender; bekræft tokenet på din server, og vis resultatet i din app.

Brug

Parametre

String
påkrævet
Den konto, opkrævningen tilhører, med præfikset biz_.
WhopElementsConfiguration
environment, returnURL og locale fungerer som alle andre steder. Standard er WhopElementsConfiguration().
WhopCharge
påkrævet
.plan(id:) eller .amount(minorUnits:currency:). Kan angives senere; næste canMakePayment() opløser den igen.
WhopSetupFutureUsage?
.offSession eller .onSession. Sæt kun, efter at du har vist samtykke til at gemme.
WhopPaymentRequest.Options
requestPayerEmail og requestBillingAddress beder arket om det, du ikke har angivet (begge har standardværdien true), og label tilsidesætter den linjepost, der vises over totalen.

WhopConfirmationToken

Det, et valg returnerer:
  • id: String: det ctok_, der skal bekræftes på serversiden
  • paymentMethodType: WhopPaymentMethodType: apple_pay på denne bane

Tilstande

canMakePayment() returnerer false, når enheden ikke kan betale, når kontoen ikke har registreret nogen Apple Pay-forhandler, eller når opkrævningen ikke kan opløses; lastError angiver hvilken. isPresenting er true fra show(), indtil den returnerer eller kaster en fejl, inklusive udstedelsen efter arket lukker; et andet show(), mens et er i gang, kaster confirmationInFlight. show() kaster walletUnavailable i stedet for at fejle lydløst, og dens besked skelner mellem en køber, der lukkede arket, og et ark, der slet ikke kunne åbne; en forhandlervalidering, som API’et afviser, kaster den API-fejl, som den blev modtaget.

Godt at vide

  • show() er et almindeligt asynkront kald, så du kan afvente det, opkrævningen har brug for, før arket vises.
  • Kombinér det med WhopApplePayButton, som er Apples egen PKPaymentButton. Apples retningslinjer kræver systemkontrollen frem for en tegnet efterligning.
  • Arket bliver bedt om en e-mail og en faktureringsadresse præcis, når du ikke har angivet dem, og dets svar udfylder kun hullerne.
  • Apple Pay-forhandleren er den, der er registreret på Whop-kontoen. Din app angiver intet og behøver ingen In-App Payments-capability.

Installation

WhopPaymentRequest kræver intet scope og intet monteret element, så det er den eneste betalingsflade, der ikke kræver WhopBrandingElement på skærmen. Vis selv merchant of record-linjen. Modulet er Elements, ikke wallet-SDK’ets WhopElements. Se Kom godt i gang.