Portal de clientes de Stripe: cómo configurarlo en tu SaaS

El portal de clientes de Stripe es una página alojada por Stripe donde tus suscriptores pueden cancelar, cambiar de plan, actualizar su tarjeta y descargar facturas anteriores, sin que tengas que construir ninguna de esas pantallas. Activas las opciones que quieras en la configuración del portal en el Dashboard, agregas un botón "Administrar facturación" que le pide a tu servidor una sesión de portal para el usuario que inició sesión, y escuchas los webhooks para que tu app se entere de lo que cambió el cliente.

En esta guía verás las dos formas de abrir el portal, qué opciones importan, el código del servidor, los webhooks que debes atender y el error que permite a un cliente ver la facturación de otro.

¿Cómo abrir el portal: enlace de acceso o API?

Stripe ofrece dos puertas de entrada.

El enlace de acceso identifica al cliente por correo. Si varios clientes de Stripe comparten la misma dirección, Stripe elige el creado más recientemente que tenga una suscripción activa, lo que puede confundir a quien tenga cuentas duplicadas. Si tu app ya tiene su propio login, el camino por API es más predecible porque tú decides exactamente qué cliente se abre.

¿Qué opciones del portal conviene activar?

Abre la página del portal de clientes dentro de la configuración de facturación del Dashboard. Los valores por defecto son un buen punto de partida, pero revisa estos grupos.

Suscripciones

• Switch plan (cambiar de plan, apagado por defecto). Actívalo y elige qué productos y precios se ofrecen. Muestra solo planes que tu app sepa manejar.
• Update quantities (cambiar cantidades, apagado por defecto). Útil si cobras por usuario.
• Prorrateo. Decide si los cambios de plan se acreditan de inmediato o al final del período.
• Bajadas de plan programadas. Puedes hacer que una bajada de plan ocurra al final del período. Stripe lo resuelve agregando un subscription schedule y solo funciona entre precios del mismo producto.

Cancelaciones

• Cancel subscription viene activado. Elige si cancela de inmediato o al final del período; en un plan mensual, al final del período es lo que la mayoría espera.
• Motivo de cancelación también viene activado, y vale la pena leer las respuestas cada mes.
• Cupones de retención (apagado por defecto): ofrecen un descuento antes de que la persona confirme la cancelación.

Datos de facturación y facturas

• Métodos de pago: activado, para que el cliente reemplace solo una tarjeta vencida.
• Historial de facturas: activado, para que descargue facturas sin escribirte.
• Información de facturación: nombre, dirección, teléfono y, si quieres, identificación fiscal.

Agrega el enlace a tus términos de servicio y una URL de regreso por defecto, y configura tu logo y colores en la página de branding. Si quieres el portal en un subdominio propio, Stripe permite un dominio personalizado por cuenta.

La configuración del portal se guarda por separado para live y para cada sandbox: configurar uno no cambia el otro. A mucha gente la sorprende el día del lanzamiento; por eso está en nuestra checklist para pasar Stripe a producción.

¿Cómo creas una sesión de portal desde tu app?

El endpoint es corto. Lo importante es de dónde sale el ID del cliente.

// POST /api/billing/portal  (corre en tu servidor)
const user = await requireSignedInUser(req);          // tu validación de sesión
const customerId = user.stripe_customer_id;            // de TU base de datos
const session = await stripe.billingPortal.sessions.create({
  customer: customerId,
  return_url: 'https://tuapp.com/cuenta',
});
return redirect(session.url);

Nunca aceptes el ID del cliente desde el navegador. Si tu endpoint toma customer del cuerpo de la petición, cualquiera puede pegar el ID de otra persona y abrir su página de facturación, con sus facturas y su dirección. Léelo de tu base de datos para el usuario con sesión iniciada.

La URL de la sesión dura poco, así que créala cuando el usuario hace clic en el botón y no la dejes guardada en la página.

¿Se puede mandar al cliente directo a una acción?

Sí. Los enlaces directos del portal usan el parámetro flow_data. Entre los tipos de flujo están payment_method_update (ir directo a "actualiza tu tarjeta"), subscription_cancel, subscription_update y subscription_update_confirm. El de actualizar tarjeta es muy útil desde un aviso de "tu pago falló", algo que vemos en pagos fallidos en Stripe.

¿Qué webhooks te dicen qué cambió el cliente?

El portal cambia cosas en Stripe, no en tu base de datos. Tu webhook las sincroniza:

• customer.subscription.updated: cambios de plan o de cantidad, y cancelaciones programadas para el final del período. En el modo de cobro clásico revisa cancel_at_period_end; en el modo flexible, si cancel_at tiene valor. Si el cliente reactiva antes de que termine el período, llega otro update con esos campos vacíos.
• customer.subscription.deleted: la suscripción terminó. Quita el acceso.
• customer.updated: cambiaron los datos de facturación o el método de pago por defecto.

La documentación de Stripe advierte que no uses el correo de facturación de estos eventos como credencial de acceso: trátalo solo como dato de facturación. Si todavía no tienes el manejador armado, la guía de suscripciones con Stripe explica la estructura.

¿Cómo lo pruebas antes de que lo usen tus clientes?

1. En un sandbox, crea un cliente de prueba con una suscripción.
2. Abre ese cliente en el Dashboard y, en el menú de acciones, usa Open customer portal para verlo como lo verá él.
3. Cancela, cambia de plan y cambia la tarjeta, mientras miras las entregas de eventos de tu endpoint.
4. Verifica que tu app muestre "termina el [fecha]" en una cancelación programada y que quite el acceso solo cuando el período termina de verdad.

Respuestas rápidas

¿El portal cuesta aparte? Es parte de Stripe Billing. Revisa los precios actuales de Billing para tu cuenta.

¿El cliente puede volver a suscribirse después de cancelar? Antes de que termine el período puede renovar desde el portal. Después, mándalo de nuevo por tu Checkout normal.

¿Puedo mostrar planes distintos a distintos clientes? Sí. Crea configuraciones adicionales del portal con la API y pasa su ID al crear la sesión. Desde el Dashboard solo se edita la configuración por defecto.

¿Por qué el portal no muestra ninguna suscripción? Casi siempre la sesión se creó para un ID de cliente distinto al dueño de la suscripción, muchas veces un cliente duplicado creado en el checkout.

¿Necesitas ayuda con la autogestión de pagos?

Si tu botón del portal abre la cuenta equivocada o tu app no se entera de las cancelaciones, nuestro servicio de pagos con Stripe cubre sesiones de portal, webhooks y validación de acceso. Empieza con la revisión gratuita de tu app, consulta la documentación del portal de clientes o escríbenos.