Elige tu flujo de guardado
Hay dos caminos, según si el usuario también está pagando en este momento.
El resto de esta página cubre el modo de configuración de principio a fin y luego muestra cómo cobrar un método guardado más adelante.
Guardar un método de pago con los payment elements
Crea el formulario de guardado con los payment elements enmode: "setup". El element ofrece solo métodos que se pueden guardar, muestra al comprador el consentimiento de uso futuro que requiere el guardado y te entrega un token de confirmación. Conviertes ese token en un setup intent desde tu servidor, y el client_secret del setup intent completa cualquier paso que el comprador tenga pendiente.
1
Monta el formulario en modo de configuración
Pasa El token incluye el consentimiento que mostró el element. El setup intent rechaza un token recopilado desde un formulario en modo de pago, así que monta en
mode="setup" y la moneda con la que se usará el método guardado. No hay importe, así que los límites de importe no se aplican. Establece returnUrl en una página que alojes sobre https. Las inscripciones bancarias y algunos flujos de 3D Secure devuelven al comprador allí.mode="setup" cuando el comprador no esté pagando.2
Crea el setup intent en tu servidor
Crea un setup intent con el token de confirmación. Whop identifica al comprador a partir del correo electrónico del token y responde
201 Created con el setup intent. Este incluye el status, un client_secret para cualquier paso que el comprador tenga pendiente y, una vez en succeeded, el método guardado como payment_method_id. Adjunta metadata para vincular el método guardado a un cliente de tu sistema. Se devuelve en el webhook. Envía una Idempotency-Key para que una solicitud reintentada nunca guarde el método dos veces.3
Completa cualquier paso pendiente
Un setup intent que vuelve como
succeeded tiene el método registrado. requires_action significa que el comprador aún tiene un paso pendiente, como 3D Secure o una inscripción bancaria. Pasa el client_secret a handleNextAction, la misma llamada que usa el flujo de pago. Ejecuta un paso en línea en un diálogo o envía al comprador a tu returnUrl. Ramifica según el status que devuelve: succeeded guardó el método, processing aún se está decidiendo y cualquier otro valor requiere otro intento. Un diálogo cerrado deja la configuración en requires_action sin error, y lastPaymentError incluye el motivo cuando el intento falla. processing significa que el procesador aún está decidiendo, así que muestra un estado pendiente y deja que el webhook siguiente confirme el guardado. canceled significa que el comprador abandonó el paso o que el proveedor rechazó el método: last_setup_error incluye el motivo del proveedor y permanece en null cuando el comprador se fue. Para leer el estado desde tu servidor, obtén el setup intent y ramifica según el mismo status, o consulta periódicamente el endpoint más ligero Retrieve setup status mientras haya un paso pendiente.4
Gestiona la finalización
Escucha el webhook El método de pago ya está guardado y autorizado para este miembro. Cóbralo con los pasos de Cobrar un método de pago guardado.
setup_intent.succeeded para obtener el ID del método de pago y recuperar tu metadata. Es la única señal que sobrevive a una pestaña cerrada, y el mismo handler sirve para el flujo alojado que se describe más abajo. El setup intent también incluye payment_instrument para mostrarlo: un nombre, el conjunto de iconos estándar y, en el caso de una tarjeta, su marca, los últimos cuatro dígitos y la fecha de caducidad. Puedes mostrar el método guardado sin otra solicitud. Los webhooks fijados a una versión anterior a la versión de API 2026-09-22-1 incluyen el método guardado como payment_method.id.Guardar un método de pago con un checkout alojado
1
Crea una configuración de checkout en modo de configuración
Crea una configuración de checkout sin variante para recopilar los datos de pago sin cobrar. Añade metadatos para poder vincular el miembro y el método de pago a un cliente de tu sistema.
2
Dirige al usuario al checkout
Monta el Checkout element o redirige al usuario para que guarde su método de pago.Una configuración en modo de configuración monta el mismo element como un guardado
de método de pago: no se cobra nada y el checkout finalizado redirige a
- Incrustado
- Redirección
returnUrl con setup_intent_id en la cadena de consulta. Confirma el guardado
desde el webhook setup_intent.succeeded y no desde la redirección.3
Gestiona la finalización
Escucha el webhook El método de pago ya está guardado y autorizado para este miembro.
setup_intent.succeeded para obtener el ID del método de pago. El setup intent incluye checkout_configuration_id y la metadata de la configuración, que puedes usar para vincular el miembro y el método de pago a un cliente de tu sistema.Confirma el guardado desde el webhook y no a partir de la llegada del comprador a tu
redirect_url. Es la única señal que sobrevive a una pestaña cerrada.Cobrar un método de pago guardado
1
Obtén el método de pago
Lista los métodos de pago guardados de un miembro o usa el
payment_method_id del setup intent del paso anterior.2
Crea un pago fuera de sesión
Cobra el método de pago sin interacción del cliente. El endpoint de creación de pagos devuelve un objeto de pago inmediatamente y procesa el cobro de forma asíncrona.
3
Gestiona los eventos de pago
Escucha los webhooks de pago para hacer seguimiento de los éxitos o fallos.
Guardar durante el checkout
Para guardar un método de pago mientras cobras al comprador, crea el checkout con los payment elements y pasasetupFutureUsage: "off_session" en el handle de Payments. Los elements muestran al comprador el consentimiento de guardado y lo registran en el token de confirmación, y el pago almacena el método solo cuando ese consentimiento está acreditado.
La propiedad de Elements para seleccionar una variante sigue llamándose plan por compatibilidad.
1
Monta el formulario con consentimiento de guardado
createConfirmationToken y handleNextAction.2
Crea el pago con el token de confirmación
La respuesta de creación es el pago tal como se abrió, no su resultado. El
payment_method_id del método guardado llega en el webhook payment.succeeded una vez que se completa el cobro.3
Cóbralo más tarde
payment_method_id es el método payt_ que debes usar en Cobrar un método de pago guardado. Permanece en null cuando no se guardó nada. El webhook payment.succeeded incluye el mismo campo, y es la vía que sobrevive a una pestaña cerrada.Próximos pasos
Aceptar pagos
Checkouts únicos y de suscripción para combinar con tu flujo de guardado.
Checkout element
Monta el checkout de Whop en tu propio sitio con Whop Elements.
Escuchar webhooks
Haz seguimiento de
setup_intent.succeeded, payment.succeeded y payment.failed.Portal de facturación
Permite que los clientes gestionen y eliminen sus métodos de pago guardados.

