Skip to main content
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:

Opciones

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.
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.
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.
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
Devuelve Promise<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
Devuelve Promise<object>
string
requerido
boolean
requerido
object | null
requerido

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".

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)