Saltar al contenido principal

Integración Stripe

Integración completa con Stripe Connect para pagos Escrow seguros en Floutic.

Características​

  • ✅ Pagos Escrow seguros - El dinero se mantiene en depósito hasta la aprobación
  • ✅ Stripe Connect - Transferencias automáticas a expertos
  • ✅ PaymentIntent inicial - Se crea al seleccionar experto
  • ✅ Sincronización automática - Estados pending → held → released
  • ✅ Liberación en cascada - Payout automatizado al aprobar hito
  • ✅ Gestión de comisiones - Comisiones automáticas para Floutic
  • ✅ Onboarding Express - Configuración rápida de cuentas Connect
  • ✅ Webhooks - Sincronización bidireccional con Stripe

Configuración​

1. Crear Cuenta en Stripe​

  1. Crear cuenta en Stripe
  2. Activar Stripe Connect
  3. Configurar cuenta Express para expertos

2. Obtener API Keys​

Modo Test:

  • STRIPE_SECRET_KEY=sk_test_...
  • STRIPE_PUBLISHABLE_KEY=pk_test_...
  • STRIPE_WEBHOOK_SECRET=whsec_...

Modo Live:

  • STRIPE_SECRET_KEY=sk_live_...
  • STRIPE_PUBLISHABLE_KEY=pk_live_...
  • STRIPE_WEBHOOK_SECRET=whsec_...

3. Configurar Webhooks​

  1. Ir a Stripe Dashboard → Webhooks
  2. Añadir endpoint: https://api.haorp.es/api/payments/webhooks/stripe
  3. Seleccionar eventos:
    • payment_intent.succeeded
    • payment_intent.payment_failed
    • payment_intent.canceled
    • charge.succeeded
    • charge.failed
  4. Copiar el Signing Secret (whsec_...)

4. Variables de Entorno​

# Stripe API Keys
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Stripe Connect
STRIPE_CONNECT_RETURN_URL=https://app.floutic.com/dashboard/experto
STRIPE_CONNECT_REFRESH_URL=https://app.floutic.com/dashboard/experto?retryStripeOnboarding=true
STRIPE_CONNECT_ACCOUNT_COUNTRY=ES

# Frontend
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
VITE_STRIPE_DASHBOARD_URL_BASE=https://dashboard.stripe.com/test/payments/

Flujo de Pagos​

1. Selección de Experto​

Cuando una empresa selecciona un experto:

  • Se crea automáticamente el PaymentIntent del primer hito
  • Estado inicial: requires_payment_method
  • El pago se muestra en la ficha del proyecto

2. Autorización del Pago​

La empresa autoriza el pago:

  • El frontend sincroniza el PaymentIntent (/api/payments/sync-status)
  • Estado cambia a requires_capture
  • El pago se marca como held en Floutic
  • Se guarda held_at y stripe_charge_id
  • Notificación: Se envía notificación payment_held al experto confirmando que los fondos están seguros.

3. Aprobación de Hito​

Cuando la empresa aprueba un hito:

  • Se captura el pago retenido (/api/payments/release-and-charge-next)
  • Se transfiere el neto al experto vía Stripe Connect
  • Se genera automáticamente el PaymentIntent del siguiente hito
  • Notificación: Se envía notificación milestone_awaiting_payment al experto para el nuevo hito.
  • El ciclo continúa hasta completar todos los hitos

4. Estados del Pago​

  • pending - PaymentIntent creado, esperando autorización
  • held - Pago autorizado, en depósito
  • released - Pago capturado y transferido al experto
  • refunded - Pago reembolsado

Stripe Connect​

Onboarding de Expertos​

Los expertos deben completar el onboarding de Stripe Connect para recibir pagos:

  1. Verificar estado: GET /api/stripe-connect/status
  2. Generar enlace: POST /api/stripe-connect/account-link
  3. Completar onboarding en Stripe
  4. Verificar estado nuevamente

Actualización de Cuenta​

Si la cuenta Connect necesita actualización:

  1. Generar enlace de actualización: POST /api/stripe-connect/account-update-link
  2. Completar actualización en Stripe
  3. Verificar estado nuevamente

Endpoints de API​

Pagos​

  • POST /api/payments/initiate - Crear PaymentIntent
  • POST /api/payments/sync-status - Sincronizar estado con Stripe
  • POST /api/payments/release - Liberar pago retenido
  • POST /api/payments/release-and-charge-next - Liberar y crear siguiente
  • POST /api/payments/refund - Crear reembolso
  • GET /api/payments/project/{project_id} - Pagos de proyecto
  • GET /api/payments/history - Historial de pagos

Stripe Connect​

  • GET /api/stripe-connect/status - Estado de cuenta Connect
  • POST /api/stripe-connect/account-link - Generar enlace de onboarding
  • POST /api/stripe-connect/account-update-link - Generar enlace de actualización

Webhooks​

Stripe envía webhooks a:

  • POST /api/payments/webhooks/stripe

Eventos procesados:

  • payment_intent.succeeded - Pago completado
  • payment_intent.payment_failed - Pago fallido
  • payment_intent.canceled - Pago cancelado
  • charge.succeeded - Cargo exitoso
  • charge.failed - Cargo fallido

Comisiones​

Floutic cobra una comisión automática en cada transferencia:

  • Configurable desde el panel de administración
  • Se calcula automáticamente en cada payout
  • Se resta del monto total antes de transferir al experto

Seguridad​

  • Validación de firmas - Todos los webhooks se validan con HMAC
  • HTTPS obligatorio - Todas las comunicaciones son seguras
  • Tokens seguros - Los PaymentIntents usan tokens únicos
  • Validación de permisos - Solo empresa/admin pueden ver enlaces a Stripe

Troubleshooting​

El pago no se sincroniza​

  1. Verificar que el webhook esté configurado correctamente
  2. Revisar logs de Stripe Dashboard
  3. Verificar STRIPE_WEBHOOK_SECRET en variables de entorno
  4. Usar POST /api/payments/sync-status para sincronización manual

El experto no recibe pagos​

  1. Verificar que tenga cuenta Connect configurada
  2. Verificar estado con GET /api/stripe-connect/status
  3. Completar onboarding si es necesario
  4. Verificar que charges_enabled y payouts_enabled sean true

Error en el onboarding​

  1. Verificar STRIPE_CONNECT_RETURN_URL y STRIPE_CONNECT_REFRESH_URL
  2. Verificar que las URLs sean HTTPS
  3. Regenerar enlace si es necesario
  4. Verificar que el país esté configurado (STRIPE_CONNECT_ACCOUNT_COUNTRY)

Documentación Completa​

Para documentación detallada, consulta:

Referencias​