Skip to main content
Esta página documenta @whop/elements@1.10.0 y @whop/elements-react@1.10.0.
Desde v1.0.0.
Se monta dentro de Payments. Pasa las props y los callbacks a través de las opciones de creación o de las props de React. Conserva el handle creado, o la ref de React, para llamar a select().
Exclusivo. PaymentElement es una alternativa a CardElement o CardFields en este handle de Payments. Monta uno cada vez. Destrúyelo antes de montar otro.
Espera a BrandingElement. Este elemento permanece en su estado de carga hasta que se monta BrandingElement en el mismo handle de Payments.
Se monta dentro de un ámbito WhopPayments. Renderiza los mosaicos de los métodos que ofrece el cobro y, después, lo que recopile el método seleccionado: los campos de tarjeta, los campos que declara o el botón de Apple Pay.
Móntalo dentro de <Payments>, que es dueño del cobro y del token de confirmación. <Payments> se monta a su vez dentro de <WhopElements>. Renderiza los mosaicos de los métodos del cobro y recopila lo que declare el método seleccionado, así que una tarjeta, una hoja de wallet y una redirección bancaria se resuelven con la misma línea.

Datos de ejemplo. Abre el Playground.

Props

string[]
Controla el orden de visualización en cualquiera de los diseños. Los tipos de la lista aparecen primero, en orden. Los tipos que no están en la lista conservan su orden relativo. No afecta a la disponibilidad. Por defecto es [].
object
Controla qué wallets ofrece el elemento. Cada clave tiene por defecto 'auto', que ofrece la wallet allí donde la cuenta, el dispositivo del comprador y el cobro la admiten. 'never' elimina esa wallet de la lista de métodos. Úsalo cuando tu página dibuje sus propios botones de Apple Pay, Google Pay o PayPal con paymentRequest, para que los compradores vean cada wallet una sola vez. payPal: 'never' elimina el método PayPal. Los métodos de pago guardados no se ven afectados. Por defecto es {}. Desde v1.8.0.
object
Controla la recopilación de los datos de facturación. billingDetails: 'minimal' (por defecto) sigue la matriz de cada método. Los métodos recopilan el nombre y el formato de país completo por defecto. Una anulación puede recopilar solo el mínimo declarado o nada. Para las tarjetas, el mínimo es el nombre en la tarjeta, el país y el código postal. 'full' exige el nombre y el formato de país completo para todos los métodos nuevos. 'never' oculta el bloque. address: 'minimal' recopila solo el mínimo declarado de cada método más un país allí donde ese mínimo no lo incluya (y también el código postal cuando billingDetails: 'full' indica que el checkout está sujeto a impuestos), excepto para wallets, cripto, débitos bancarios, transferencias bancarias, pagos con tarjeta presente y compras dentro de la app, que no recopilan ninguna dirección, y excepto para un método cuyo proveedor exige la dirección de facturación completa (requires_full_billing_address), cuyo mosaico sigue las mismas reglas que un checkout sin esa marca; en los demás casos prevalece sobre billingDetails: 'full'; úsalo cuando el vendedor no recopile una dirección de facturación completa. phone: 'never' oculta solo el campo de teléfono de facturación cuando tu formulario ya lo recopila; pasa billingDetails.phone a createConfirmationToken para los métodos que lo requieran. En su lugar, pasa la dirección a createConfirmationToken. El selector de país incluye solo los países que admiten el método y la moneda del pago. Con un plan de pago a plazos seleccionado, se limita a los países que cubre el plan: el país de facturación es el país de la transacción con el que se procesa el cobro. Se bloquea cuando solo hay uno disponible. Por defecto es {"billingDetails":"minimal"}.
object
Rellena previamente los datos de facturación cuando el bloque de facturación de cada método se renderiza por primera vez. El comprador puede editar todos los campos rellenados. address.country es un código ISO 3166-1 alfa-2 y solo se aplica cuando el método seleccionado lo acepta. phone rellena el campo de teléfono de facturación de los métodos que lo recopilan, en formato E.164 como +14155552671; se ignora un número fuera de los países de teléfono admitidos por el método. Solo se rellenan y envían los campos que renderiza el bloque. Pasa cualquier otro dato a createConfirmationToken en billingDetails. Desde v1.1.0.
"accordion" | "horizontal"
Diseño del selector. accordion (por defecto) apila los métodos y despliega los detalles en línea. horizontal muestra mosaicos del mismo ancho y sin desplazamiento, con los detalles del seleccionado debajo. A partir de cuatro métodos, un mosaico More abre un selector nativo. El método elegido allí ocupa el último mosaico hasta la siguiente selección. La selección y la confirmación se comportan igual. Por defecto es "accordion".
boolean
Solo para accordion. Añade espaciado y un estilo de tarjeta separado entre los métodos. Se ignora cuando layout es horizontal. Por defecto es false.
boolean
Si se selecciona el primer método ofrecido tras la resolución. El valor por defecto true respeta order y emite selected y change como una interacción del comprador. Se ejecuta una vez antes de la interacción del comprador y no hace nada cuando no se ofrece ningún método. Establécelo en false para montar sin selección. Independientemente de esto, si una actualización elimina el método seleccionado, la selección recurre al primer método ofrecido. Un elemento que ya no tiene selección se queda sin selección. Por defecto es true.

Eventos

Pasa los callbacks en las opciones de creación o como props de React.

onChange

Se dispara cuando cambia la selección. complete: true significa que el comprador seleccionó un método y completó sus campos de tarjeta o sus campos obligatorios. Úsalo para habilitar la confirmación. paymentMethod es el método de pago seleccionado, guardado o nuevo, o null mientras no hay nada seleccionado: displayName e icons nombran la elección tal como la muestra el elemento (con balance.imageUrl, la imagen del titular de un saldo), card incluye la red, los últimos cuatro dígitos y el tipo de financiación de una tarjeta, requiresBillingPhone indica si el método necesita un teléfono en los datos de facturación y countries enumera desde dónde puede pagar el método en la moneda del cobro. type, requiresBillingPhone y method en el nivel superior están obsoletos: léelos desde paymentMethod. supportsBuyerFee en el nivel superior también está obsoleto, sin reemplazo: Whop fija el precio de su tarifa de servicio al comprador por sí mismo.
PaymentElementChangeEvent

onAddressChange

Se dispara unos 300 ms después de que cambie la dirección de facturación interna. Úsalo para impuestos, envío u otras actualizaciones que dependen de la dirección. country es un código ISO 3166-1 alfa-2. El payload omite las demás claves de la dirección cuando están vacías o no se usan en ese país. complete: true significa que el bloque de facturación es válido y está completo. Este evento solo se dispara mientras el elemento de pago se encarga de recopilar la dirección. Con fields.billingDetails: 'never', usa tu propia fuente de dirección. Con un AddressElement montado, usa su evento change.
object

onLoaderStart

Se ejecuta después de que el esqueleto de carga se pinta por primera vez y antes de onReady.

onReady

Se ejecuta después del primer pintado completo del elemento.

onError

Se ejecuta cuando el elemento no se carga o falla. El contenido de respaldo permanece visible. Usa code para el manejo programático. sourceKey identifica una fuente de estado del host que falló.
object

Métodos

Llámalos en el handle que devuelve create, o a través de una ref de React.

select

Selecciona un método por la misma vía que una interacción del comprador. Por ejemplo, select('cashapp') despliega el mosaico y emite selected y change. Las tarjetas siguen en complete: false hasta que sus campos estén completos. Los métodos desconocidos, no disponibles o limitados por importe se rechazan con el código METHOD_NOT_OFFERED. select(null) borra la selección y emite change con complete: false. Úsalo con autoSelect={false} para tener control externo total.Parámetros
string | null
requerido
Devuelve Promise<void>

mount

Monta el elemento en target y comienza a cargarlo. Los componentes de React se montan solos.Parámetros
string | HTMLElement
requerido

destroy

Elimina el elemento y libera su frame y sus suscripciones. Puedes llamarlo más de una vez. React elimina el elemento automáticamente.

update

Combina nuevas props en el elemento montado. En React, cambia las props del componente en su lugar.Parámetros
Partial<PaymentElementProps>
requerido

Estilos

Aplica estilo a estas partes mediante appearance.classes. Usa camel case o kebab case para los nombres de las propiedades e incluye las unidades. Las hojas de estilo de la página no pueden llegar al frame del elemento. El framework valida cada declaración antes de inyectarla.
En React, pasa appearance a <Payments>. Establécelo globalmente con WhopElements({ appearance }).

Parámetros

[WhopPaymentMethodType]
Orden de los mosaicos para este montaje, que anula el methodOrder del controlador. Los tipos de la lista ocupan su posición en la lista; el resto conserva su orden de entrada detrás de ellos.
Binding<WhopPaymentSelection>?
Lee de vuelta la selección actual y si está completa. El controlador registra ambas cosas en cualquier caso.

WhopPaymentSelection

Lo que devuelve una selección:
  • isComplete: Bool: el método seleccionado tiene todo lo que necesita
  • type: WhopPaymentMethodType?: el método seleccionado
  • displayName: String?: su etiqueta, tal como la escribe la matriz
  • category: String?: card, wallet, bank_debit, …

Estados

Muestra mosaicos de esqueleto mientras se carga la matriz de métodos y el mensaje de error cuando falla la lectura. Un método cuya categoría no puede ejecutar esta compilación se omite en lugar de renderizarse como un mosaico roto. Seleccionar una wallet cambia la superficie de confirmación por Apple Pay.

Información útil

  • Apple Pay no necesita nada de tu app: ni identificador de comerciante ni la capacidad In-App Payments. El comerciante es el registrado en la cuenta de Whop, y el mosaico se renderiza siempre que el dispositivo pueda pagar.
  • Un método que declara un campo secure lo renderiza como un campo alojado. Esos valores nunca entran en tu proceso.
  • Los métodos guardados de un comprador con sesión iniciada aparecen encima de los nuevos. Monta WhopEmailElement para ofrecer el inicio de sesión que genera la credencial; elegir una fila guardada no recopila nada y genera una referencia.
  • Un cobro con tarjeta que publica niveles de pago a plazos muestra un selector de plan dentro del panel de la tarjeta. Un plan que la tarjeta del comprador no admite se contrae en lugar de atenuarse, y un plan cuya región no se corresponde con el país de facturación se rechaza antes de que se ejecute cualquier tokenizador.
  • Un mercado que exige un documento de identidad (hoy, un cobro en ars) renderiza el selector de tipo y el campo de número dentro del panel. Ese número pasa por tu app de camino al tokenizador, a diferencia de la tarjeta, y aun así nunca llega a Whop.
  • Los valores de la tarjeta y de los campos seguros se tokenizan antes de la generación, así que el token de confirmación es lo único que pasa por tu app.
  • Monta WhopAddressElement junto a él cuando un método necesite un país de facturación: la lista de mosaicos se limita a los métodos que ese país permite.

Instalación

Móntalo dentro de un ámbito WhopPayments(accountID:charge:), que crea el controlador y se lo pasa a su contenido. payments.buyer es el comprador con sesión iniciada una vez que un inicio de sesión por correo electrónico lo ha verificado. WhopBrandingElement también tiene que estar en pantalla, porque Whop es el comerciante registrado en estas ventas y createConfirmationToken se rechaza sin él. Aplica estilo con .whopElementsAppearance(_:). El módulo es Elements, no WhopElements del SDK de wallet. Consulta Primeros pasos y Appearance.

Props

string[]
Orden de visualización de los métodos, con la semántica de paymentMethodOrder de Stripe. Los tipos que no están en la lista conservan su orden relativo de entrada detrás de los de la lista. También se puede establecer una vez en <Payments>.
(payload: PaymentChangePayload) => void
Se dispara con cada cambio de selección y de completitud. Condiciona tu botón de envío a complete.
StyleProp<ViewStyle>
Se aplica al View exterior del elemento. Para la personalización del tema, es preferible appearance.parts en el provider, que cubre todos los elementos de esta superficie. Ten en cuenta que, por ahora, los nombres de las partes de React Native son un conjunto propio, no los nombres de clase whop-* de la web, por lo que un objeto de appearance de la web no se puede trasladar sin cambios.
ReactNode
Se renderiza en lugar del esqueleto integrado mientras el elemento se carga.
() => void
Se dispara una vez que el elemento es interactivo. <Payments> los agrupa, así que normalmente lo que quieres es su propio onLoadingChange.
(error: { message: string; code?: string }) => void
Un fallo de carga o de configuración de este elemento. En cualquier caso, el elemento renderiza su propia vista de error.

PaymentChangePayload

Lo que devuelve onChange:
  • complete: boolean: el método seleccionado tiene todo lo que necesita
  • type?: string: el tipo de método seleccionado, por ejemplo card
  • method?: { type, category, template, display_name }: la entrada del método seleccionado en la matriz

Estados

Tres filas de esqueleto hasta que llega la matriz de métodos y, después, los mosaicos. Seleccionar un mosaico despliega su región de detalle debajo. onChange informa de complete cuando el método seleccionado tiene todo lo que necesita, que es lo que condiciona tu botón de envío. Un cobro sin ningún método apto renderiza un estado vacío explicativo en lugar de nada.

Información útil

  • Los números de tarjeta nunca pasan por tu código. Los campos son entradas nativas aisladas según PCI, y el SDK entrega a Whop un token, de modo que tu app queda fuera del alcance de PCI.
  • Apple Pay y Google Pay presentan la hoja propia de la plataforma. Ninguno necesita nada de ti: Apple Pay usa el comerciante registrado en la cuenta de Whop, así que no hay identificador de comerciante que pasar ni capacidad que añadir en Xcode, y googlePayMerchantName solo establece el nombre que se muestra en la hoja, que por defecto es Whop.
  • Los métodos de redirección y 3D Secure abren ASWebAuthenticationSession en iOS y Custom Tabs en Android. Siempre el navegador del sistema, nunca una WebView, para que la página del emisor quede fuera del límite de confianza de tu app.
  • Establece returnUrl en <Payments> con una URL https que tú alojes. La API rechaza cualquier cosa que no sea https o loopback (PaymentsApi::ValidateReturnUrl), así que aquí no hay disponible un esquema de app personalizado. No registras ningún deep link: después de que el emisor redirija, handleNextAction consulta el pago hasta que se estabiliza y cierra el navegador por sí mismo.
Envuelve tu app en <WhopElements getToken={…}> una vez y luego monta <Payments> alrededor de los elementos. Consulta Primeros pasos y Appearance.