desarrollo-webintermedio

Stripe Connect en Next.js: arquitectura segura, onboarding y webhooks

Diseña Stripe Connect en Next.js con onboarding, webhooks verificados e idempotencia.

5 min de lectura
94 vistas
26 de octubre de 2026
LG
Luis Granero
Desarrollador Web Full Stack

Una plataforma que cobra a compradores y transfiere importes a vendedores necesita más que un botón de pagar. Debe definir quién es la parte vendedora, quién asume comisiones y disputas, cómo se incorporan las cuentas y qué ocurre cuando un evento llega dos veces o fuera de orden.

Stripe Connect proporciona herramientas para plataformas y marketplaces. Esta guía presenta una arquitectura didáctica; para producción hay que escoger el modelo de cuentas y pagos aplicable a la plataforma, al país y a las capacidades disponibles en la API vigente.

Antes del código: decide el flujo del dinero

Tres decisiones gobiernan todo el diseño: quién recibe el cargo, cómo se distribuyen los fondos y quién responde de reembolsos y contracargos. Stripe distingue tres tipos de cargo en Connect: cargos directos, cargos de destino y cargos y transferencias separados (documentación de tipos de cargo). No son intercambiables; comisiones, obligaciones y eventos dependen del modelo elegido. En los cargos directos, los reembolsos y disputas se descuentan del saldo de la cuenta conectada; en los de destino y en los cargos y transferencias separados, del saldo de la plataforma. Stripe indica que los cargos directos suelen ser apropiados cuando la plataforma no intermedia en la relación comercial, mientras que los cargos de destino o separados ofrecen más control cuando la plataforma cobra centralmente y redistribuye después. La elección depende de quién actúa como vendedor ante el cliente, de cómo se gestionan las comisiones y de las obligaciones fiscales de cada modelo; revisa la guía de recomendaciones de integración antes de decidir.

Documenta el flujo con ejemplos concretos de pago completado, pago fallido, reembolso parcial, reclamación y cuenta restringida. No intentes modelar únicamente el camino feliz.

Modelo de datos mínimo

Guarda una relación segura entre tu tenant y su cuenta conectada (stripeAccountId), el estado de incorporación, los identificadores de pagos y transferencias, y un registro de eventos procesados. No almacenes números completos de tarjeta ni CVV. Define permisos por tenant para evitar que una organización consulte el estado de otra.

Un esquema mínimo para una integración SaaS con Stripe Connect podría incluir estas entidades:

Entidad Propósito Campo clave
tenant Organización que usa la plataforma id, stripeAccountId, onboardingStatus
payment Transacción registrada id, stripePaymentIntentId, stripeChargeId, amount, currency, status
transfer Movimiento de fondos hacia el tenant id, stripeTransferId, amount, status
webhook_event Evento procesado de Stripe id, stripeEventId, type, processedAt, payload

La tabla webhook_event debe tener una restricción única en stripeEventId para garantizar la deduplicación. El campo onboardingStatus en tenant refleja el estado de incorporación (none, incomplete, approved, rejected, chargedback) y debe consultarse después de cada redirección de onboarding, no confiar ciegamente en el enlace devuelto.

Los requisitos de cada tabla varían según el tipo de cargo elegido. En cargos directos, la plataforma no necesita registrar el monto cobrado directamente; en cargos de destino o separados, sí debe rastrear tanto el cargo como la transferencia por separado.

La clave secreta de Stripe vive exclusivamente en el servidor. Las variables con prefijo público son para datos deliberadamente publicables, nunca para secretos.

Incorporación de vendedores

El onboarding requiere crear o asociar una cuenta conectada según el modelo actual, obtener un enlace o sesión de incorporación apropiado (por ejemplo, el onboarding alojado por Stripe) y redirigir al usuario. Al regresar, no asumas que ya puede cobrar: consulta el estado en Stripe y comprueba capacidades y requisitos pendientes.

Los enlaces de onboarding pueden caducar y deben regenerarse en un flujo autenticado y validado. Verifica que quien solicita el enlace tiene permiso para administrar ese tenant.

Ruta webhook con verificación de firma

Los webhooks son esenciales porque un cliente puede cerrar la ventana después del pago. Según la documentación de webhooks de Stripe, el servidor debe verificar la firma con el cuerpo sin modificar y devolver un 2xx rápidamente, antes de ejecutar lógica compleja que pueda provocar un timeout. Ejemplo orientativo para un Route Handler de Next.js:

import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: NextRequest) {
  const signature = req.headers.get('stripe-signature');
  if (!signature || !process.env.STRIPE_WEBHOOK_SECRET) {
    return new NextResponse('Missing configuration or signature', { status: 400 });
  }

  let event: Stripe.Event;
  try {
    const payload = await req.text();
    event = stripe.webhooks.constructEvent(
      payload,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch {
    return new NextResponse('Invalid signature', { status: 400 });
  }

  // Persistir event.id de forma atómica y encolar su procesamiento.
  // No ejecutar aquí una mutación de negocio sin idempotencia.
  return NextResponse.json({ received: true });
}

Advertencia: el ejemplo valida la firma pero no procesa pagos. Responder 2xx sin persistir y encolar correctamente el evento puede perder trabajo. Implementa persistencia y cola durables antes de usarlo en producción.

Probar webhooks localmente con Stripe CLI

Durante el desarrollo, los webhooks no pueden llegar a un endpoint local sin una URL pública. Stripe CLI resuelve este problema mediante un tunnel seguro que reenvía los eventos de Stripe a tu servidor local:

stripe listen --forward-to localhost:3002/api/payments/webhook

El comando imprime un webhook signing secret que debes usar en lugar del que configuras en el dashboard de Stripe para el entorno de desarrollo. Esto evita conflictos entre la verificación local y la producción. Stripe CLI también permite simular eventos específicos:

stripe trigger payment_intent.succeeded

Esto facilita las pruebas de casos extremos (reembolsos, disputas, fallos de pago) sin necesidad de transacciones reales. Never use production secrets in local testing; keep the test mode keys and the local signing secret isolated from production credentials.

Versionado de la API de Stripe

Stripe utiliza versionado basado en fechas (2026-09-30.endive, por ejemplo). Cuando usas un SDK servidor, las llamadas emplean la versión de API vigente en el momento del release del SDK. Si actualizas el SDK sin revisar el changelog, puedes encontrar comportamientos modificados o campos obsoletos.

Para mantener la coherencia:

  • Asigna la versión de API en el cliente SDK (stripe_version) en lugar de depender de la versión por defecto.
  • Suscríbete al changelog de Stripe para conocer los cambios entre versiones.
  • En entornos multi-tenant, prueba cada actualización de SDK en staging antes de producirla.
  • documenta la versión de API que usa cada servicio; un cambio inesperado puede romper contratos de eventos webhook.

La documentación oficial sobre versionado explica cómo se propaga cada versión a través de SDKs, la CLI y la API reference.

Idempotencia y orden de eventos

Stripe puede reenviar un evento. Usa el event.id como identificador de deduplicación con restricción única en base de datos y cambios de estado transaccionales. Stripe también advierte de que, en algunos casos, se generan dos objetos Event distintos para el mismo hecho; para detectarlos usa el ID de data.object junto con event.type. Además, Stripe no garantiza que los eventos lleguen en el orden en que se generaron: cuando el estado sea crítico, consulta el recurso canónico en Stripe antes de aplicar transiciones.

Las claves de idempotencia en peticiones API salientes evitan crear operaciones duplicadas durante reintentos, pero no sustituyen la deduplicación de webhooks.

Gestión de fallos y conciliación

Registra IDs de eventos y objetos, nunca secretos ni datos de tarjeta. Configura alertas ante reintentos agotados, cuentas restringidas y diferencias entre estados internos y Stripe. Un proceso periódico de conciliación debe detectar pagos procesados externamente pero no reflejados en el sistema.

Prueba explícitamente: webhook duplicado, entrega tardía, firma inválida, caída de base de datos, disputa, reembolso y cambio de capacidades de una cuenta. Usa el modo de pruebas y las herramientas de prueba de Connect de Stripe.

Seguridad multi-tenant

No permitas que el frontend elija libremente un stripeAccountId para operar. Obtén la cuenta desde la relación tenant-usuario validada en servidor. Revisa políticas de acceso a datos, separación de ambientes, logs, rotación de credenciales, permisos y protección frente a replay.

Preguntas frecuentes

¿Stripe Connect es igual que Stripe Checkout?

No. Checkout ayuda con la experiencia de pago; Connect gestiona necesidades específicas de plataformas y cuentas conectadas. Pueden utilizarse juntos en arquitecturas compatibles.

¿Puedo confirmar un pago solo por la página de éxito?

No es una fuente fiable. Usa eventos verificados y consulta el estado oficial cuando sea necesario.

¿Por qué necesito guardar los eventos?

Para deduplicar, auditar reintentos y recuperar procesos tras errores.

Conclusión

La prioridad en pagos multi-tenant no es escribir menos código: es diseñar contabilidad, estados, autorización e idempotencia antes de mover dinero real. Verifica siempre la documentación y las capacidades actualizadas de Stripe para tu modelo.

Fuentes oficiales

Lectura relacionada: Guía completa de Next.js. Si construyes una plataforma con pagos, consulta el servicio de desarrollo SaaS.

¿Te ha resultado útil? Compártelo