Skip to main content
Esta página documenta @whop/elements@1.10.0 y @whop/elements-react@1.10.0.
Desde v1.0.0.
Crea este recurso de Payments sin montar ningún elemento: whop.payments.paymentRequest.create({ … }) en vanilla o useWhop().payments.paymentRequest.create({ … }) en React.

Opciones

Pásalas a whop.payments.paymentRequest.create({ … }).
string
requerido
ID de la cuenta, con el prefijo biz_, que delimita todas las llamadas del lado del cliente.
string
requerido
Código de moneda de pago ISO 4217 de tres letras.
number
requerido
Importe del pago en unidades menores. Cámbialo más tarde con update().
"off_session" | "on_session"
Establécelo solo después de mostrar el consentimiento para guardar. Marca el token para uso off_session u on_session.
PaymentMethodConfigurationShape
Filtros de métodos de pago en el formato enabled, disabled e include_platform_defaults de la API. Limitan las wallets que informa canMakePayment(): disabled elimina tipos, enabled restaura tipos ofrecidos e include_platform_defaults: false deja solo los tipos habilitados. Nunca añaden un método que la cuenta no ofrezca. PayPal sigue el tipo paypal. Desde v1.9.0.
boolean
Pide a la hoja el email del pagador: el token de confirmación requiere uno. Por defecto es true.
boolean
Pide a la hoja el número de teléfono del pagador, que se entrega como payer.phone en el resultado: en E.164 cuando se puede interpretar según el país del contacto que lo proporcionó y, si no, tal como lo dio la wallet; payer.country es el país de facturación. Google Pay lo recopila mediante la dirección de facturación que la hoja ya pide. PayPal lo recopila mediante su sección de contacto y rechaza una cuenta que no lo tenga. Por defecto es false.
boolean
Pide a la hoja una dirección de envío (y ofrece shippingOptions cuando se indican). PayPal siempre pide una dirección, ya que es la dirección sobre la que se calculan los impuestos, y la devuelve como shipping solo cuando esto está establecido. Por defecto es false.
boolean
Ofrece el campo de código promocional propio de la hoja y responde a onPromoCodeChange. Apple Pay muestra el campo en dispositivos compatibles con la versión 12 de Apple Pay (iOS 15 y macOS 12); Google Pay lo muestra donde la configuración de Google Pay de la cuenta permite ofertas. Otros dispositivos abren la hoja sin él. Por defecto es false. Desde v1.5.0.
string
Un código promocional ya aplicado al cobro, rellenado previamente en la hoja para que el comprador pueda verlo, sustituirlo o eliminarlo. Desde v1.5.0.
string
Lo que hace appliedPromoCode, que se muestra junto al código en Google Pay. El campo de cupón de Apple Pay no tiene leyenda. Desde v1.5.0.
string
Código de país ISO 3166-1 alfa-2 de la cuenta para la hoja de Apple Pay. Omítelo para usar el país de registro publicado de la cuenta. La hoja usa US por defecto cuando no hay ninguno disponible.
PaymentRequestLineItem[]
Partidas que la hoja enumera debajo del total. Cámbialas más tarde con update().
PaymentRequestShippingOption[]
Opciones de envío que ofrece la hoja cuando requestShipping está establecido. Solo de visualización: actualiza amount desde tu controlador de cambios. La hoja se abre con la primera opción seleccionada y no dispara onShippingOptionChange para ella, así que amount ya debe incluir su precio. Cámbialas más tarde con update().

Métodos

Llámalos en el recurso.
Llama a show de forma síncrona durante la activación del usuario. Espera primero los requisitos previos.

canMakePayment

Devuelve la disponibilidad de cada wallet cuando la cuenta la ofrece, el dispositivo la admite y el origen de esta página está aprobado para la cuenta (las páginas propias de whop.com están aprobadas de antemano; una página de comerciante necesita tener Apple Pay preparado en su dominio mediante la API de Domains, y ofrecer Google Pay en ella está sujeto a los Términos de servicio de la API de Google Pay). En una página que está a su vez dentro de un iframe, Apple Pay comprueba en su lugar el dominio de la página de nivel superior cuando el navegador lo expone. Apple Pay en navegadores que no son WebKit es el flujo de traspaso al iPhone de escritorio, así que los dispositivos móviles de esos navegadores lo indican como no disponible; Apple Pay nativo en navegadores de iOS no se ve afectado. order clasifica las wallets según qué hoja es nativa del navegador (Apple Pay primero en Safari, Google Pay primero en los demás, PayPal al final) para que los botones de express checkout se puedan apilar de mejor a peor. payPal indica PayPal cuando la cuenta lo ofrece en esta moneda, el importe está dentro de los límites de PayPal, la solicitud no pide el teléfono del pagador (una solicitud off_session puede ser de $0, lo que guarda PayPal sin cobrar), los scripts de PayPal se cargan en esta página y el origen de esta página está aprobado para la cuenta igual que para las demás wallets. Una página con Content Security Policy debe permitir los hosts de PayPal, que contentSecurityPolicy() incluye. Una página que ya carga el SDK de JavaScript v5 propio de PayPal indica payPal: false. Pasa types para comprobar solo las wallets que enumeres; show(type) necesita que esa wallet se haya comprobado. wallets incluye el arte oficial del botón de cada wallet disponible (color e imagen light y dark). Esto prepara show(). Espera siempre a que termine primero.Parámetros
object
Devuelve Promise<WalletAvailability>
boolean
requerido
boolean
requerido
boolean
("apple_pay" | "google_pay" | "paypal_express")[]
Las wallets clasificadas según qué hoja es nativa de este navegador (Apple Pay primero en WebKit, Google Pay primero en todos los demás, PayPal al final) para que los botones de express checkout se puedan apilar de mejor a peor. No está presente en la disponibilidad declarada por el consumidor (vistas previas) ni en conexiones anteriores a esta función. Una unión en línea, no el WalletSheetType de payment-request: ese módulo ya importa este.
object
Los detalles de cada wallet disponible, con el tipo de wallet como clave. No está presente en la disponibilidad declarada por el consumidor (vistas previas).

show

Abre la wallet seleccionada después de esperar a canMakePayment(), de forma síncrona en la pulsación: Apple exige que la sesión se cree dentro de la pila del gesto, y PayPal abre su ventana ahí (una ventana emergente en escritorio, y la ventana integrada en la página de PayPal cuando la ventana emergente está bloqueada y en móvil). Pasa email cuando tu página ya haya recopilado uno: la wallet lo toma y nunca pide un segundo. Con requestPayerEmail: false, pasarlo es obligatorio, y la wallet se niega a abrirse sin él porque los tokens de confirmación requieren un email. Mientras la hoja está abierta, update() lanza una excepción: responde a los eventos de cambio para modificarla. Llámalo de forma síncrona durante la activación del usuario. Espera primero a los requisitos previos, porque los navegadores revocan la activación entre pasos asíncronos.Parámetros
"apple_pay" | "google_pay" | "paypal_express"
requerido
object
Devuelve Promise<PaymentRequestResult>
string
requerido
ID del token de confirmación, con el prefijo ctok_. Confírmalo en el servidor con tu clave secreta.
"apple_pay" | "google_pay" | "paypal_express"
requerido
object
requerido
phone está en E.164 cuando se pudo interpretar según el país del contacto y, si no, tal como se dio; PayPal solo lo proporciona con requestPayerPhone y rechaza una cuenta que no lo tenga. country es el país de facturación que recopilan todas las hojas.
object | null
requerido
La dirección de facturación completa que incluye el token de confirmación, a diferencia de la redactada que incluyen los eventos de cambio; null cuando la wallet no dio ninguna. Apple Pay y Google Pay dan la dirección de facturación de la tarjeta. En PayPal es la dirección que el comprador eligió en PayPal, aquella sobre la que se calcularon los impuestos de su total.
object | null
requerido
null a menos que se haya establecido requestShipping. option es la opción de envío seleccionada: la primera ofrecida hasta que el comprador elige otra, y de nuevo la primera cuando una respuesta sustituyó las opciones sin el id elegido. Apple Pay y Google Pay la establecen siempre que se ofrecieron opciones, y PayPal nunca lo hace.

update

Cambia amount, lineItems y shippingOptions en esta instancia. Todas las demás opciones se fijan en create(): crea una nueva instancia para cambiarlas.Parámetros
object
requerido

Eventos

Suscríbete a los eventos de abajo. Cada método devuelve una función para cancelar la suscripción.
Cada controlador de eventos debe llamar a su método de respuesta documentado exactamente una vez. Un controlador que lanza una excepción o se rechaza antes de responder hace fallar esa actualización de inmediato.

onShippingAddressChange

El comprador eligió una dirección de envío (redactada antes de la autorización: solo ciudad, estado, código postal y país; Apple Pay recorta un código ZIP de EE. UU. a cinco dígitos y elimina los tres últimos caracteres de un código postal de Canadá o del Reino Unido). Responde con los totales para la dirección y la opción de envío seleccionada: la primera hasta que el comprador elija otra. shippingOptions sustituye las opciones (una lista vacía no cambia nada). Una opción elegida sigue seleccionada mientras la respuesta conserve su id; cuando la respuesta la elimina, la primera opción pasa a ser la selección sin un onShippingOptionChange, así que pon precio a esa. Todos los errores de la respuesta permanecen en la dirección hasta que una respuesta posterior para una dirección los borre: uno que nombra un field (city, state, postal_code, country) marca ese campo en Apple Pay, y Google Pay muestra solo el mensaje. El pago se rechaza mientras haya un error en la dirección. Rechaza una dirección a la que no puedas enviar con un error shipping_address_unserviceable y sin field. En Apple Pay, Google Pay y PayPal, un controlador que no ha respondido en 25 segundos hace fallar la dirección, igual que uno que lanza una excepción, y su respuesta posterior se ignora. PayPal lo dispara con la dirección que elige el comprador, y un error que nombra un field rechaza esa parte de la dirección dentro de PayPal. Llama a updateWith(…) exactamente una vez por evento. Un controlador que lanza una excepción o se rechaza antes de llamarlo hace fallar esa actualización de inmediato. Devuelve la función para cancelar la suscripción.
ShippingAddressChangeEvent

onShippingOptionChange

El comprador eligió una opción de envío, o Apple Pay volvió a anunciar la seleccionada: una vez respondidos todos los cambios de dirección y sin ninguno pendiente, Apple Pay lo dispara para la opción que sigue seleccionada. Nunca se dispara después de una respuesta que elimina la opción seleccionada, lo que convierte la primera opción en la selección sin ningún evento, así que cada total que respondas pone precio a la opción seleccionada: la primera hasta que el comprador elija otra, la elegida mientras tus respuestas conserven su id, y de nuevo la primera en cuanto una respuesta la elimine. Contrato solo de importe: updateWith lleva amount/lineItems/shippingOptions/errors. Una respuesta con errors rechaza la opción hasta que el comprador elija una que tu controlador acepte. Apple Pay no tiene espacio para errores en una opción de envío, así que conserva el último total aceptado sea lo que sea lo que incluya la respuesta, y el mensaje del primer error aparece cuando el comprador pulsa Pagar. Google Pay muestra el mensaje cuando se elige la opción. En Apple Pay, Google Pay y PayPal, un controlador que no ha respondido en 25 segundos rechaza la opción, igual que uno que lanza una excepción, y su respuesta posterior se ignora. Llama a updateWith(…) exactamente una vez por evento. Un controlador que lanza una excepción o se rechaza antes de llamarlo hace fallar esa actualización de inmediato. Devuelve la función para cancelar la suscripción.
ShippingOptionChangeEvent

onBillingAddressChange

El comprador seleccionó una tarjeta, con su dirección de facturación redactada (solo ciudad, estado, código postal y país): recalcula el total para la dirección sobre la que el cobro calcula los impuestos. Apple Pay lo dispara cuando el comprador selecciona una tarjeta, y Google Pay cuando se abre la hoja y cada vez que el comprador cambia de tarjeta. Responde updateWith({ amount }) en unidades menores, updateWith({}) para mantener el total actual o updateWith({ errors }) para rechazar la tarjeta. Cada evento se responde exactamente una vez: un controlador que lanza una excepción, se rechaza o no responde en 10 segundos rechaza la tarjeta, así que el comprador elige otra. En Apple Pay y Google Pay, la misma selección dispara después paymentMethodChange, y la hoja se actualiza cuando ambos se han respondido. PayPal lo dispara con cada dirección de envío que el comprador elige en PayPal, que es la dirección a la que su token factura y sobre la que calcula los impuestos, y un rechazo ahí rechaza esa dirección dentro de PayPal. Llama a updateWith(…) exactamente una vez por evento. Un controlador que lanza una excepción o se rechaza antes de llamarlo hace fallar esa actualización de inmediato. Devuelve la función para cancelar la suscripción.
BillingAddressChangeEvent

onPaymentMethodChange

El comprador seleccionó un método de pago: recalcula el total para él, por ejemplo con un recargo en las tarjetas de crédito. Apple Pay lo dispara cuando el comprador selecciona una tarjeta, y Google Pay cuando se abre la hoja y cada vez que el comprador cambia de tarjeta, en cada caso justo después del billingAddressChange de esa tarjeta. paymentMethod.type es card. paymentMethod.card incluye lo que la wallet indica sobre una tarjeta antes de que el comprador autorice: Apple Pay informa de su funding (Apple normalmente oculta la red hasta entonces) y Google Pay de su network. paymentMethod.billingAddress es la dirección de facturación redactada de la tarjeta. Responde updateWith({ amount, lineItems }) para recalcular el precio, updateWith({}) para mantener el total actual o updateWith({ errors }) para rechazar el método; shippingOptions se ignora. Apple Pay marca un rechazo en el contacto de facturación de la tarjeta (en el field indicado, si lo hay) y retiene su botón Pagar hasta que el comprador elige otro método. Google Pay muestra el mensaje en la tarjeta y rechaza pulsar Pagar con ella hasta que el comprador elija una tarjeta que aceptes. Una tarjeta rechazada deja los totales como estaban, sea cual sea el precio que hayan calculado esta respuesta o la respuesta a su billingAddressChange. Cada evento se responde exactamente una vez: un controlador que lanza una excepción, se rechaza o no responde en 10 segundos rechaza el método. Cada hoja espera tu respuesta antes de que el comprador pueda pagar. PayPal nunca lo dispara. Llama a updateWith(…) exactamente una vez por evento. Un controlador que lanza una excepción o se rechaza antes de llamarlo hace fallar esa actualización de inmediato. Devuelve la función para cancelar la suscripción.
PaymentMethodChangeEvent

onPromoCodeChange

El comprador escribió, cambió o eliminó un código en el campo promocional de la hoja (requestPromoCode). Responde updateWith({ amount }) para aplicar el código con un nuevo total, updateWith({}) para aplicarlo con el total actual o updateWith({ error }) para rechazarlo en el mismo lugar. Una eliminación llega con code en null y se responde de la misma manera. Sustituir un código aplicado llega como un único evento con el nuevo código, nunca primero como una eliminación, y un código nuevo rechazado deja en su sitio el aplicado. Cuando shippingOptions elimina la opción seleccionada, la primera pasa a ser la selección sin un onShippingOptionChange, así que pon precio a esa. appliedDescription añade una leyenda al código en Google Pay; el campo de cupón de Apple Pay no tiene leyenda, así que pon lo que el comprador deba ver en la etiqueta de una partida. Un controlador que lanza una excepción, se rechaza o no responde en 10 segundos rechaza el código. Llama a updateWith(…) exactamente una vez por evento. Un controlador que lanza una excepción o se rechaza antes de llamarlo hace fallar esa actualización de inmediato. Devuelve la función para cancelar la suscripción.
PromoCodeChangeEvent

onPaymentAuthorization

El comprador autorizó el pago y todavía no existe ningún token de confirmación. Suscríbete para aprobarlo o rechazarlo primero: la hoja espera tu respuesta y, sin un controlador, el token se crea de inmediato. El evento incluye el pagador, el método de pago (con su dirección de facturación redactada y, en displayName, la etiqueta propia de la wallet, como Visa 1234), la dirección y la opción de envío, y el total y las partidas que autorizó el comprador. Responde respondWith({ approved: true }) para crear el token, que show() y onConfirmationToken entregan luego como de costumbre. Responde respondWith({ approved: false, message }) para rechazarlo: no se crea ningún token, Apple Pay y Google Pay muestran message en la hoja, y el comprador puede cambiar algo y volver a pagar, o cerrar la hoja. PayPal no puede mostrar tu mensaje, así que un rechazo ahí termina el intento: show() se rechaza con payment_request_refused, y el comprador puede volver a pulsar PayPal. Cada evento se responde exactamente una vez, y solo approved: true crea un token: un controlador que lanza una excepción, se rechaza o no responde en 25 segundos rechaza el pago, con tiempo suficiente para que Apple Pay y Google Pay muestren el rechazo antes de su propio límite de 30 segundos. Llama a respondWith(…) exactamente una vez por evento. Un controlador que lanza una excepción o se rechaza antes de llamarlo hace fallar esa actualización de inmediato. Devuelve la función para cancelar la suscripción.
PaymentAuthorizationEvent

onConfirmationToken

La hoja creó un token de confirmación, que se recibe una vez que la hoja se ha cerrado. Es el mismo resultado que devuelve show(). Devuelve la función para cancelar la suscripción.
PaymentRequestResult

onCancel

El comprador descartó la hoja o cerró PayPal. Devuelve la función para cancelar la suscripción.

Content Security Policy

Este recurso se ejecuta en tu página, no en un frame. Una página con Content Security Policy necesita estas fuentes. contentSecurityPolicy() de @whop/elements devuelve todas las fuentes de esta tabla. La fuente de sandbox se aplica con environment: "sandbox".
En iOS esto es solo Apple Pay: Google Pay es una vía web de show(type) sin equivalente en Swift. Sin elemento y sin controlador: un objeto que controlas tú mismo, para un botón de express checkout encima del formulario. canMakePayment() prepara la hoja y show() se resuelve con el mismo ctok_ que genera un elemento. La hoja se cierra con una marca de éxito en cuanto el cliente autoriza; confirma el token en tu servidor y muestra el resultado en tu app.

Uso

Parámetros

String
requerido
La cuenta a la que pertenece el cobro, con el prefijo biz_.
WhopElementsConfiguration
environment, returnURL y locale se comportan igual que en todas partes. Por defecto es WhopElementsConfiguration().
WhopCharge
requerido
.plan(id:) o .amount(minorUnits:currency:). Se puede establecer más tarde; el siguiente canMakePayment() lo vuelve a resolver.
WhopSetupFutureUsage?
.offSession o .onSession. Establécelo solo después de mostrar el consentimiento para guardar.
WhopPaymentRequest.Options
requestPayerEmail y requestBillingAddress piden a la hoja lo que no hayas proporcionado (ambos son true por defecto), y label anula la partida que se muestra encima del total.

WhopConfirmationToken

Lo que devuelve una selección:
  • id: String: el ctok_ que se confirma en el servidor
  • paymentMethodType: WhopPaymentMethodType: apple_pay en esta vía

Estados

canMakePayment() devuelve false cuando el dispositivo no puede pagar, cuando la cuenta no tiene ningún comerciante de Apple Pay registrado o cuando el cobro no se puede resolver; lastError indica cuál. isPresenting es true desde show() hasta que devuelve un resultado o lanza una excepción, incluida la generación después de que se cierre la hoja; un segundo show() mientras hay uno en curso lanza confirmationInFlight. show() lanza walletUnavailable en lugar de fallar en silencio, y su mensaje distingue a un comprador que descartó la hoja de una hoja que no se pudo abrir; una validación de comerciante que la API rechaza lanza ese error de la API tal como se recibió.

Información útil

  • show() es una llamada asíncrona normal, así que puedes esperar lo que necesite el cobro antes de presentar la hoja.
  • Combínalo con WhopApplePayButton, que es el propio PKPaymentButton de Apple. Las directrices de Apple exigen el control del sistema en lugar de una imitación dibujada.
  • A la hoja se le pide un email y una dirección de facturación exactamente cuando no los has proporcionado, y sus respuestas solo rellenan los huecos.
  • El comerciante de Apple Pay es el registrado en la cuenta de Whop. Tu app no proporciona nada y no necesita la capacidad In-App Payments.

Instalación

WhopPaymentRequest no necesita ámbito ni elemento montado, así que es la única superficie de pagos que no requiere WhopBrandingElement en pantalla. Muestra tú mismo la línea del comerciante registrado. El módulo es Elements, no WhopElements del SDK de wallet. Consulta Primeros pasos.