Cobra un pago a partir de un ID plan_ o de una moneda y un importe en línea, o guarda un método de pago sin cobrar con mode: "setup". Monta PaymentElement, CardElement o CardFields y luego llama a payments.createConfirmationToken con los datos de facturación. Las selecciones de billetera abren su hoja automáticamente. Cuando la cuenta ofrece vinculación bancaria en la página (bank_debit.bank_connection en su tipo de método de pago de cuenta bancaria), seleccionar una cuenta bancaria también abre Plaid Link en la página. Si el comprador cierra cualquiera de las dos, la llamada se rechaza con payment_request_cancelled, que tu handler de pago debe tratar como una cancelación. Confirma el token en el servidor y luego pasa el client_secret del pago o del setup intent a handleNextAction para cualquier paso pendiente.
Esta página documenta @whop/elements@1.10.0 y @whop/elements-react@1.10.0.
Desde v1.0.0.
Playground
Combina los elementos con datos de ejemplo. Usa los controles, añade y organiza elementos, y observa cómo se disparan los eventos en vivo:
import { WhopElements, Payments } from "@whop/elements-react";import { loadWhop } from "@whop/elements";function Example() { return ( <WhopElements elements={loadWhop()}> <Payments /* options */> {/* mount elements here */} </Payments> </WhopElements> );}
Pásalas a whop.payments.create({ … }), o como props de <Payments> en React.
Pasa exactamente una de estas combinaciones:
accountId y plan
accountId, currency y amount
accountId, mode: "setup" y currency
ninguno de plan, currency, amount o mode
string
ID de la cuenta, con el prefijo biz_. Omítelo solo al llamar a métodos estáticos sin una superficie de cuenta.
"payment" | "setup"
Modo de montaje, payment de forma predeterminada. setup guarda un método de pago y no cobra nada, ni ahora ni después: solo se ofrecen los métodos que se pueden guardar y no se aplican los límites de importe. Confirma con createConfirmationToken() y luego crea el setup intent en el servidor.
string
ID del plan, con el prefijo plan_. Se resuelve en el cliente en la moneda, el importe y la configuración de métodos. Pasa un plan o una moneda y un importe en línea, nunca ambos.
object
Totales feeInclusive y feeFree en unidades menores que se usan para filtrar los métodos cuando el checkout recalcula amount para un método sin comisión, como BNPL. Cada método se compara con su total correspondiente, lo que evita que desaparezca el método sin comisión seleccionado. Si se omite, amount filtra todos los métodos.
Mostrar propiedades
number
requerido
number
requerido
string
URL de retorno para pasos bancarios externos o de 3DS. De forma predeterminada, es la página de montaje. El comprador llega ahí sea cual sea el resultado, con payment (o setup), status (succeeded, failed, canceled o un estado aún pendiente como processing) y client_secret añadidos, así que ramifica según status antes de mostrar una página de éxito.
"off_session" | "on_session"
Un setup guarda el método de pago para uso off_session, el único uso que acepta un setup.
WalletAvailability
Anulación de la disponibilidad de billeteras para vistas previas deterministas. Los checkouts en vivo sondean el host.
Mostrar propiedades
boolean
requerido
boolean
requerido
boolean
("apple_pay" | "google_pay" | "paypal_express")[]
Las billeteras ordenadas 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 exprés se apilen empezando por el mejor. Ausente en la disponibilidad indicada por el consumidor (vistas previas) y en los formatos de datos anteriores a ella. Una unión en línea, no el WalletSheetType de payment-request: ese módulo ya importa este.
object
Los detalles de cada billetera disponible, con el tipo de billetera como clave. Ausente en la disponibilidad indicada por el consumidor (vistas previas).
Mostrar propiedades
WalletDetails
Mostrar propiedades
WalletButtonArt
El diseño oficial del botón de la billetera. Ausente cuando no se ha publicado ninguno.
Mostrar propiedades
object
requerido
Para páginas claras.
Mostrar propiedades
string
requerido
string
requerido
object
requerido
Para páginas oscuras.
Mostrar propiedades
string
requerido
string
requerido
WalletDetails
Mostrar propiedades
WalletButtonArt
El diseño oficial del botón de la billetera. Ausente cuando no se ha publicado ninguno.
Mostrar propiedades
object
requerido
Para páginas claras.
Mostrar propiedades
string
requerido
string
requerido
object
requerido
Para páginas oscuras.
Mostrar propiedades
string
requerido
string
requerido
WalletDetails
Mostrar propiedades
WalletButtonArt
El diseño oficial del botón de la billetera. Ausente cuando no se ha publicado ninguno.
Mostrar propiedades
object
requerido
Para páginas claras.
Mostrar propiedades
string
requerido
string
requerido
object
requerido
Para páginas oscuras.
Mostrar propiedades
string
requerido
string
requerido
string
Código de moneda ISO 4217 de tres letras en minúsculas. Filtra la matriz de métodos de pago.
number
Importe del pago en unidades menores. No se ofrecen los métodos cuyos límites lo excluyen.
object
Filtros de métodos de pago de la cuenta en el formato enabled, disabled e include_platform_defaults de la API. disabled elimina tipos, enabled restaura tipos ofrecidos e include_platform_defaults: false deja solo los tipos habilitados. Los planes proporcionan su propia configuración.
Mostrar propiedades
string[]
string[]
boolean
Appearance
Personalización visual de los elementos de este grupo. Sobrescribe el WhopElements({ appearance }) global. Cámbialo en vivo con update({ appearance }).
WhopElementsLocale
Configuración regional del texto de la interfaz de los elementos de este grupo. Establécela en una de las configuraciones regionales incluidas en la app para sobrescribir la configuración global. Cualquier otro valor recurre a la configuración regional predeterminada.
Eventos
Pasa los callbacks en las opciones de creación o como props de React.
onLoadingChange
Se ejecuta cuando cambia el estado de carga agrupado. El valor es true mientras algún elemento montado siga cargándose.
boolean
Métodos
Llámalos en el handle de Payments obtenido de whop.payments.create({ … }) o usePayments().
createConfirmationToken
Crea un token de confirmación para el método seleccionado desde tu botón de pago. Pasa los datos de facturación del checkout. Deben incluir email. Proporciona phone para los métodos que lo requieren cuando la recopilación de datos de facturación está desactivada. Las tarjetas también necesitan name y una dirección que contenga line1 y country. Las selecciones de billetera abren su hoja durante la interacción con el botón de pago. Cuando la cuenta ofrece vinculación bancaria en la página (bank_debit.bank_connection en su tipo de método de pago de cuenta bancaria), seleccionar una cuenta bancaria también abre Plaid Link durante esa interacción, y la llamada se resuelve una vez que el comprador ha vinculado una cuenta. Eso requiere una página de whop.com o un dominio preparado para Apple Pay mediante la API de Domains, y una Content Security Policy que permita los hosts de Plaid que devuelve contentSecurityPolicy(). De lo contrario, el comprador vincula la cuenta después de enviar el pago. Si el comprador cierra la hoja o Link, la llamada se rechaza con payment_request_cancelled: trátalo como una cancelación, no como un error de pago, y deja que el comprador vuelva a pagar. Confirma el confirmationToken devuelto en el servidor y luego llama a WhopElements.payments.handleNextAction(…). Se ejecuta en tu página (en el host), no en el iframe del controlador.Parámetros
object
requerido
Ocultar propiedades
object
Mostrar propiedades
string
string
string
object
Mostrar propiedades
string
string
string
string
string
string
DevuelvePromise<object>
string
requerido
string
requerido
update
Combina nuevas opciones del handle en todos los elementos montados. En React, cambia las props del namespace en su lugar.Parámetros
Partial<PaymentsOptions>
requerido
destroy
Destruye todos los elementos y subcontroladores que creó este handle, elimina el frame del controlador y libera sus suscripciones. Puedes llamarlo más de una vez, pero un handle destruido rechaza cualquier otra llamada: crea un nuevo handle para empezar de nuevo. React elimina el grupo automáticamente cuando el provider se desmonta.
Métodos estáticos
Llámalos sin montar nada: whop.payments.<method>(…) en vanilla o useWhop().payments.<method>(…) en React.
handleNextAction
Completa el paso pendiente de un pago confirmado sin montar un elemento. clientSecret identifica el pago. No necesitas un ID de pago. Los pasos en línea se abren en un diálogo y se resuelven con redirected: false. Cerrar el diálogo devuelve el estado actual del pago, que puede seguir pendiente. Los pasos de página completa redirigen con redirected: true a return_url, o a un recibo alojado cuando el pago no tiene URL de retorno. Dentro de un iframe, navegan en la pestaña de nivel superior. Si la página contenedora rechaza esa navegación, se rechazan con el código TAB_NAVIGATION_BLOCKED y el pago sigue pendiente. Establece returnUrl para actualizar el destino antes de la presentación. Un fallo en la actualización se rechaza antes de que se ejecute cualquier paso. Los pasos en línea nunca navegan a esa URL. Un pago cuyo cobro aún se está decidiendo se consulta periódicamente hasta que aparece un paso o se resuelve; un pago ya decidido sin ningún paso se resuelve inmediatamente.Parámetros
object
requerido
Ocultar propiedades
string
requerido
string
number
DevuelvePromise<object>
string
requerido
boolean
requerido
object | null
requerido
Mostrar propiedades
string | null
string | null
string | null
Recursos
Crea estos objetos del SDK sin montar un elemento. Cada uno tiene su propia página:
PaymentRequest
Hoja de bajo nivel de Apple Pay, Google Pay o PayPal para botones personalizados, checkout exprés y callbacks de envío. Los mosaicos de billetera automatizan este flujo mediante payments.createConfirmationToken. Espera a canMakePayment() para comprobar la disponibilidad y preparar la billetera, y luego llama a show(type) de forma síncrona en el handler de la interacción del usuario. El ctok resuelto es un token de confirmación con el prefijo ctok_. Confírmalo en el servidor como un token emitido por un elemento. Un token de PayPal cobra como máximo el total que PayPal mostró al comprador.
Política de seguridad de contenido
Parte del trabajo de este grupo se ejecuta en tu página, no en un frame. Una página con una Content Security Policy necesita estos orígenes. contentSecurityPolicy() de @whop/elements devuelve todos los orígenes de esta tabla. El origen de sandbox se aplica con environment: "sandbox".
Requisito
Directiva
Origen en producción
Origen en sandbox
Script de Plaid Link
script-src
https://cdn.plaid.com
Igual
↳ Frame de Plaid Link, que abre el script de Plaid
frame-src
https://cdn.plaid.com
Igual
↳ API de Plaid, a la que llama el script de Plaid
connect-src
https://production.plaid.com
https://sandbox.plaid.com
Elementos
Los elementos que monta este grupo. Cada uno tiene su propia página:
AddressElement
Recopila una dirección de facturación o de envío. Los campos, su orden y la validación siguen el país seleccionado. Incluye autocompletado de la calle (a pantalla completa en teléfonos) y métodos para leer o validar la dirección.
EmailElement
Recopila el correo electrónico del comprador y lo pasa a payments.createConfirmationToken() mientras está montado. Un billingDetails.email explícito tiene prioridad. Si coincide con una cuenta de Whop, muestra un inicio de sesión opcional con verificación por código, o con la passkey de la cuenta si tiene una. Un inicio de sesión correcto desbloquea los métodos de pago guardados en el elemento de pago. Los compradores pueden continuar como invitados.
TaxIdElement
Recopila un registro fiscal empresarial aceptado por la API. Las etiquetas usan nombres orientados al comprador. El marcador de posición coincide con el formato seleccionado. country preselecciona un tipo. onChange emite los pares confirmados. El host proporciona los errores de validación de la API.
BrandingElement
Obligatorio: los demás elementos, excepto AddressElement, EmailElement y TaxIdElement, lo esperan. El aviso de comerciante registrado (merchant of record) de Whop: la aceptación por parte del comprador de los Términos de servicio para compradores y la Política de privacidad de Whop, con el logotipo textual de Whop. Obligatorio: los elementos de pago, de tarjeta y de campos de tarjeta permanecen en su estado de carga hasta que se monta, y los pagos no pueden confirmarse sin él.
Alternativas. Monta uno a la vez. Destrúyelo antes de montar otro:
PaymentElement
Muestra los métodos de pago disponibles y recopila los campos obligatorios y los avisos del método seleccionado. Usa change para habilitar tu botón de pago. En su handler de activación, llama a payments.createConfirmationToken(). Confirma el token en el servidor y luego pasa cualquier paso pendiente a payments.handleNextAction(…). Usa addressChange para actualizaciones que dependen de la dirección.
CardElement
Campos predispuestos para el número de tarjeta, la fecha de vencimiento y el código de seguridad. Créalo con payments.create("card"), habilita tu botón de pago desde onChange y confirma con payments.createConfirmationToken(). Los números de tarjeta permanecen en campos alojados aislados según PCI. layout admite stacked (predeterminado) y compact.
CardFields
Tres campos de tarjeta montables por separado y aislados según PCI para diseños personalizados: número, fecha de vencimiento y código de seguridad. Créalo con payments.create("cardFields"), coloca cada campo, habilita tu botón de pago desde onChange y confirma con payments.createConfirmationToken(). Los números de tarjeta permanecen en campos alojados. (subcontrolador, 3 elementos)
Assistant
Responses are generated using AI and may contain mistakes.