Skip to main content
Usa métodos de pago guardados para cobrar automáticamente a los clientes por suscripciones, renovaciones o facturación basada en el uso. El cliente guarda su tarjeta una vez mediante un flujo alojado o incrustado de Whop, y puedes cobrarle en cualquier momento después.
Combina esta guía con los webhooks: escucha setup_intent.succeeded para confirmar el guardado y luego payment.succeeded / payment.failed para hacer seguimiento de los cobros futuros.

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 en mode: "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 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í.
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" 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 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.
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.

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 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 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.
El ejemplo usa waitUntil de @vercel/functions para ejecutar el handler después de responder 200. En otros runtimes (Bun, Cloudflare Workers, Fastify, Hono), sustitúyelo por la primitiva equivalente de tareas en segundo plano de tu framework o por una cola de trabajos. Consulta la guía de webhooks para ver handlers equivalentes en Python y Ruby.
El método de pago ya está guardado y autorizado para este miembro.

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.
También puedes enviar line_items para combinar variantes existentes con precios creados en línea. Cada elemento acepta exactamente uno de variant_id o variant:
Crear una variante requiere plan:create además de payment:charge. Reutilizar una variante coincidente por product_id solo necesita payment:charge. Una definición de product en línea también requiere access_pass:create para crear el producto, o access_pass:update para actualizar uno existente. Las variantes deben pertenecer a la cuenta del pago y cumplir las reglas de compatibilidad del carrito. La variant en línea usa el mismo comportamiento de buscar o crear que una variant de nivel superior. Pasa force_create_new_plan: true para forzar una variante nueva. Los campos anidados de variante y producto siguen Api-Version-Date, y las propiedades desconocidas se rechazan. Usa una Idempotency-Key para repetir la solicitud sin crear otro pago.Para aplicar un descuento, pasa el ID de uno de tus códigos promocionales como promo_code_id y Whop calcula el precio con descuento por ti. El código promocional debe estar activo y ser válido para la variante, y la variante debe pertenecer a un producto.
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 pasa setupFutureUsage: "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

Crear un checkout con payment elements explica el botón de pago, 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.