Guía: Sistema de Pagos Escrow

Esta guía explica cómo funciona el sistema de pagos Escrow en Floutic, que garantiza transacciones seguras entre empresas y expertos.

¿Qué es Escrow?

Escrow es un sistema de depósito en garantía donde el dinero se mantiene en custodia por un tercero (Floutic) hasta que se cumplen ciertas condiciones. Esto protege tanto a empresas como a expertos.

Resumen del Flujo

Aceptar Propuesta → Crear PaymentIntent → Confirmar Pago (notificación al experto) → Trabajar en Hitos →
Entregar Hito → Aprobar Entrega → Capturar Pago → Transferir a Experto

:::info Notificación al experto Cuando el pago se confirma (manualmente, por webhook de Stripe, o por sincronización), el experto recibe automáticamente un email "Pago Confirmado — Proyecto Iniciado" y una notificación en tiempo real. Esto cubre la transición payment_pending → in_progress. :::

Paso 1: Configuración Inicial

1.1 Para Empresas

No requiere configuración especial:

• Solo necesitas una tarjeta de crédito/débito válida
• El sistema crea automáticamente los pagos cuando aceptas una propuesta
• No necesitas cuenta Stripe

1.2 Para Expertos

Debes configurar Stripe Connect:

1. Primera vez que aceptas una propuesta:

   • El sistema te pedirá configurar pagos
   • O ve a: Dashboard → Configuración → Pagos

2. Completa el onboarding de Stripe Connect:

   • Información personal (nombre, email)
   • Datos fiscales (NIF, dirección)
   • Información bancaria (IBAN)
   • Documentos de identidad (si es necesario)

3. Espera aprobación:

   • Normalmente instantánea en modo test
   • Puede tomar 1-2 días en producción

⚠️ Importante: Sin Stripe Connect configurado, no podrás recibir pagos.

Paso 2: Aceptar Propuesta y Crear Escrow

Cuando una empresa acepta tu propuesta:

2.1 Creación Automática de PaymentIntent

El sistema automáticamente:

1. Crea un PaymentIntent en Stripe
2. Reserva el dinero de la tarjeta de la empresa
3. NO cobra el dinero aún (solo se reserva)
4. Estado inicial: pending

Información del pago:

• Monto total del proyecto
• Desglose por hitos
• Estado actual
• Fechas estimadas

2.2 Ver Detalles del Pago

Desde el dashboard:

1. Ve al proyecto → Pestaña "Pagos"
2. Verás:
   • Monto total reservado
   • Estado del pago
   • Desglose por hitos
   • Historial de transacciones

Paso 3: Estados del Pago

3.1 Estados Principales

Estado	Descripción	Cuándo Ocurre
pending	Dinero reservado, esperando trabajo	Al aceptar propuesta
held	Fondos retenidos en escrow (autorizados)	Tras confirmación/sync con Stripe
released	Pago capturado por la plataforma	Al aprobar entrega
refunded	Dinero reembolsado	Si se cancela proyecto

3.2 Estados de Transferencia (payout_status)

Una vez que el pago está released, la transferencia al experto se gestiona por separado:

payout_status	Descripción	Cuándo Ocurre
pending	Transferencia pendiente (fondos no disponibles)	Al capturar si balance insuficiente
transferred	Transferencia completada exitosamente	Cuando el scheduler transfiere
failed	Transferencia fallida tras reintentos	Después de 5 intentos fallidos

:::info Transferencia diferida (Deferred Payout) En Stripe LIVE, los fondos capturados tardan ~5 días hábiles en setlear (disponerse) en la cuenta de la plataforma. Si el balance de la plataforma es insuficiente al momento de la aprobación, el pago queda en released con payout_status=pending y un scheduler diario reintenta la transferencia automáticamente. :::

3.3 Flujo de Estados

pending → held → released → (transferencia) → payout_status=transferred
   ↓         ↓        ↓
refunded  refunded  payout_status=pending → scheduler → transferred/failed

Paso 4: Trabajar en Hitos

Estado del pago: pending

Mientras trabajas:

• El dinero está reservado pero no cobrado
• La empresa puede cancelar y recibir reembolso completo
• No recibes dinero hasta aprobar entregas

Qué hacer:

1. Trabaja en el hito normalmente
2. Completa el trabajo según especificaciones
3. Sube la entrega cuando esté lista

Paso 5: Entregar Hito

Cuando subes una entrega:

5.1 Cambio de Estado

El sistema automáticamente:

1. Registra la entrega para revisión de la empresa
2. Mantiene el pago en pending o held según estado real en Stripe
3. La empresa puede revisar la entrega
4. NO se transfiere hasta aprobar

Estado del pago del hito: pending o held (sin liberación aún)

5.2 Qué Significa "Held"

Para la empresa:

• El dinero está retenido
• Puede aprobar o rechazar
• Si rechaza, el dinero vuelve a pending

Para el experto:

• El trabajo está completado
• Esperando aprobación
• El dinero se transferirá al aprobar

Paso 6: Aprobar Entrega

:::info Requisito previo Para aprobar una entrega de un hito con importe > 0€, debe existir un pago en estado held para ese hito. Si el pago no existe (por ejemplo, nunca se creó o se perdió por un error anterior), la aprobación se rechaza con PAYMENT_MISSING. Solo los hitos gratuitos (amount = 0€) pueden aprobarse sin pago. :::

Cuando la empresa aprueba tu entrega:

6.1 Captura del Pago

El sistema automáticamente:

1. Captura el pago del hito (inmediato)
2. Cobra el dinero de la tarjeta de la empresa
3. Intenta transferir el neto a tu cuenta Stripe Connect
4. Si hay saldo disponible: la transferencia se procesa → payout_status=transferred
5. Si NO hay saldo (fondos pendientes de settlement): el pago queda released con payout_status=pending → el scheduler reintenta automáticamente

Estado del pago del hito: held → released

6.2 Transferencia a Stripe Connect

Antes de transferir, el sistema valida una serie de condiciones de seguridad y cumplimiento. Si alguna falla, la transferencia se rechaza y el pago queda en estado released para intervención:

Validación	Condición	Error si falla
Connect activo	stripe_connect_status == "active"	STRIPE_CONNECT_NOT_ACTIVE
DAC7 completo	has_complete_fiscal_data() del experto	DAC7_DATA_INCOMPLETE
Importe válido	expert_amount > 0 (la comisión no se traga todo el pago)	INVALID_COMMISSION_CONFIGURATION

:::info Validaciones antes de capturar El estado de Connect y los datos fiscales DAC7 se verifican antes de cualquier captura o transferencia. Si el experto no tiene su cuenta Connect activa o sus datos fiscales incompletos, la empresa debe esperar a que el experto regularice su situación desde Configuración → Pagos. :::

La transferencia NO siempre es inmediata. En Stripe LIVE, los fondos capturados tardan ~5 días hábiles en setlearse. Si el balance de la plataforma no tiene saldo disponible al momento de la aprobación, el sistema diferice la transferencia y un scheduler diario reintenta.

6.3 Creación Automática del Siguiente Pago

Tras una transferencia exitosa, el sistema crea automáticamente el PaymentIntent para el siguiente hito del proyecto y lo deja en estado awaiting_payment. La empresa puede pagar el siguiente hito directamente desde la UI.

Si la creación del siguiente pago falla por un error transitorio (timeout de Stripe, caída de red), el approval actual se completa igualmente (la transferencia al experto ya se hizo) y el sistema registra el error en logs. La empresa puede crear el pago manualmente desde la pestaña de Pagos.

Cuando la transferencia se procesa:

• Stripe transfiere el neto a tu cuenta Connect
• payout_status cambia a transferred
• Disponible en tu cuenta Stripe Connect: 2-7 días hábiles adicionales

Si la transferencia falla:

• payout_status cambia a failed tras 5 intentos
• Se revierte el hito (approved → in_progress) y la entrega (approved → submitted) para que la empresa pueda reaprobar una vez resuelto el problema
• Se alerta a los admins si el fallo deja un hito siguiente huérfano (creado en awaiting_payment durante la aprobación)
• Se notifica al experto y a los admins con un mensaje legible (no el código crudo de Stripe)
• Un admin puede reintentar manualmente desde el dashboard (acepta estados held+failed y released+pending)

Webhooks de transferencia:

Webhook	Acción
transfer.created	Registra la transferencia, actualiza payout_status a pending
transfer.failed	Revierte hito y entrega, marca la transferencia como fallida, recalcula expert_amount y notifica al experto y admins

Información disponible:

• Monto transferido
• Fecha de transferencia
• Estado de la transferencia
• Comisiones deducidas

6.3 Payout a Cuenta Bancaria

Una vez que el dinero llega a la cuenta Stripe Connect del experto, Stripe procesa automáticamente un payout a la cuenta bancaria configurada.

:::info El payout es a nivel de cuenta El payout no corresponde a una sola transferencia. Stripe agrega todas las transferencias pendientes de la cuenta Connect y las envía como un solo pago bancario. Esto significa que múltiples hitos aprobados pueden llegar en un único depósito bancario. :::

Webhooks de payout:

Webhook	Acción	Notificación
payout.paid	Marca payout como completado	Solo in-app (sin email)
payout.failed	Marca payout como fallido, notifica al experto y admins	Solo in-app (sin email)

Tiempo del payout:

• Stripe procesa el payout automáticamente
• Depósito en cuenta bancaria: 2-7 días hábiles adicionales
• Total estimado desde aprobación: 4-14 días hábiles

Paso 7: Rechazar Entrega

Si la empresa rechaza tu entrega:

7.1 Reversión del Pago

El sistema automáticamente:

1. Revierte el estado del pago
2. El dinero vuelve a: pending
3. NO se cobra el dinero
4. Puedes subir una nueva versión

Estado del pago del hito: held → pending

7.2 Hacer Correcciones

Qué hacer:

1. Lee los comentarios de la empresa
2. Haz las correcciones necesarias
3. Sube una nueva versión de la entrega
4. El proceso se repite hasta aprobar

Paso 8: Cancelación de Proyecto

8.1 Cancelación Antes de Iniciar

Si se cancela antes de empezar trabajo:

• Reembolso completo a la empresa
• No se cobra ningún dinero
• Estado: refunded

8.2 Cancelación Durante el Proyecto

Si se cancela durante el trabajo:

Según hitos completados:

• Hitos completados y aprobados: Se pagan normalmente
• Hitos completados pero no aprobados: Se reembolsan
• Hitos no iniciados: Se reembolsan

Proceso:

1. Admin o empresa cancela el proyecto
2. Sistema calcula qué pagar y qué reembolsar
3. Procesa pagos de hitos aprobados
4. Reembolsa el resto a la empresa

Reembolsos

Cuando un pago se reembolsa (ya sea por cancelación de proyecto o acción manual), el sistema procesa automáticamente el reembolso a través de Stripe y notifica a ambas partes.

Flujo del Reembolso

Cuando se procesa un reembolso:

1. Stripe emite el reembolso en el PaymentIntent
2. El webhook charge.refunded se dispara en Floutic
3. El sistema marca el pago como refunded
4. El hito revierte su estado a awaiting_payment
5. Se envían notificaciones a ambas partes

:::warning Reembolso de un pago ya liberado Si el pago ya estaba released y se había transferido al experto, el sistema revierte la transferencia (create_transfer_reversal) antes de emitir el reembolso. La reversión puede ser total o proporcional al monto reembolsado. Si la reversión falla, el reembolso no se procesa (para evitar que la plataforma absorba el dinero del experto). El ID y monto de la reversión quedan registrados en payment_metadata para auditoría. :::

Qué recibe el Experto

• Email (payment_refunded.html con is_expert=True): Informa que el pago fue devuelto a la empresa, estado actual del hito y recomendaciones
• Notificación in-app: Confirma el reembolso en el dashboard

Qué recibe la Empresa

• Email (payment_refunded.html con is_expert=False): Confirma el reembolso, plazo estimado de devolución (5-10 días hábiles), y cómo reanudar el proyecto
• Notificación in-app: Confirma el reembolso en el dashboard

:::tip Plazo de devolución El reembolso aparece en la tarjeta de la empresa en 5-10 días hábiles, dependiendo del banco emisor. La empresa recibirá un email de confirmación con el plazo estimado. :::

Disputas (Chargebacks)

Una disputa (o chargeback) ocurre cuando el titular de una tarjeta contacta a su banco para impugnar un cargo. Esto es diferente de un reembolso initiated desde Floutic.

Qué es una Disputa

• El titular de la tarjeta (la empresa) contacta a su banco y disputa el cargo
• El banco abre una investigación y retira temporalmente los fondos
• Stripe notifica a Floutic para que pueda responder con evidencia

Flujo Automático

Webhook	Acción	Notificación
charge.dispute.created	Crea registro de disputa, marca pago como disputed	Solo in-app (sin email)
charge.dispute.updated	Actualiza estado de la disputa	Solo in-app (sin email)
charge.dispute.closed	Resuelve la disputa (ganada o perdida)	Solo in-app (sin email)

:::warning Las disputas NO envían emails A diferencia de los reembolsos, las disputas solo generan notificaciones in-app. Ni el experto ni la empresa reciben emails durante el proceso de disputa. Esto es intencional para evitar confusión con el proceso de reembolso normal. :::

Timeline de la Disputa

1. Día 0: El banco abre la disputa. Stripe notifica a Floutic.
2. Día 0-7: Floutic puede recopilar evidencia (entregas, comunicaciones, aprobaciones).
3. Día 7-21: Stripe envía la respuesta al banco con la evidencia.
4. Resolución: El banco decide (puede tardar semanas).

Posibles Resultados

• Disputa ganada: Los fondos vuelven a Floutic. Un administrador decide si se devuelve al experto o se reembolsa a la empresa.
• Disputa perdida: El pago se reembolsa definitivamente a la empresa. Se procesa como un reembolso normal.

Paso 9: Verificar Pagos

9.1 Desde el Dashboard de Floutic

Información disponible:

• Estado de cada hito
• Monto de cada pago
• Fecha de cada transacción
• Historial completo

9.2 Desde Stripe Dashboard

Para expertos:

1. Accede a tu cuenta Stripe
2. Ve a: Balance → Transfers
3. Verás:
   • Todas las transferencias recibidas
   • Montos y fechas
   • Estado de cada transferencia
   • Comisiones deducidas

Paso 10: Comisiones

10.1 Comisión de la Plataforma

Floutic cobra una comisión:

• Porcentaje configurable por el admin
• Se deduce del monto total del proyecto
• Se muestra claramente antes de aceptar

Ejemplo:

• Proyecto: €1,000
• Comisión (10%): €100
• Experto recibe: €900

10.2 Comisiones de Stripe

Stripe también cobra comisiones:

• Por transacción: ~2.9% + €0.30
• Se deduce automáticamente
• Visible en tu dashboard de Stripe

Ejemplo:

• Transferencia: €900
• Comisión Stripe: €26.40
• Recibes: €873.60

Troubleshooting

Problema: No Recibo Pagos

Posibles causas:

1. Stripe Connect no configurado:

   • Ve a Configuración → Pagos
   • Completa el onboarding

2. Stripe Connect pendiente:

   • Verifica estado en Stripe
   • Completa información faltante

3. Entregas no aprobadas:

   • Solo se pagan hitos aprobados
   • Verifica estado de entregas

Problema: Pago Retrasado

Tiempos normales:

• Aprobación: Inmediata
• Captura: Inmediata
• Transferencia a Stripe: Depends on platform balance (immediate if funds available, deferred if not)

Si la transferencia está diferida (payout_status=pending):

• Es normal en Stripe LIVE — los fondos tardan ~5 días hábiles en setearse
• El scheduler diario reintenta automáticamente cuando hay saldo
• No requiere acción del experto — se procesa solo
• Reintento manual (admin): si el scheduler está desactivado, un admin puede forzar el reintento desde POST /api/payments/retry-transfer/{payment_id}, que ahora acepta tanto pagos held+failed como released+pending

Si tarda más de 7 días:

• Verifica estado en Stripe Dashboard → Balance
• Contacta soporte si es necesario

Problema: Reembolso Incorrecto

Si hay problemas:

1. Verifica el historial de pagos
2. Revisa los hitos completados
3. Contacta soporte con detalles
4. Proporciona evidencia si es necesario

Problema: Se ha abierto una disputa

Qué hacer:

1. No entres en pánico — las disputas son parte del comercio electrónico
2. Revisa la notificación in-app con los detalles de la disputa
3. Recopila evidencia: entregas aprobadas, comunicaciones en el chat, hitos completados
4. Contacta a soporte (hola@floutic.com) para que Floutic pueda responder a Stripe con la evidencia
5. Stripe da 7-21 días para responder — no esperes al último momento

:::warning Las disputas son sensibles al tiempo Stripe da un plazo limitado para responder. Si no se proporciona evidencia a tiempo, la disputa se pierde automáticamente. Contacta a soporte lo antes posible. :::

Problema: Mi transferencia falló

Posibles causas:

• Cuenta bancaria inválida: Verifica que el IBAN sea correcto en tu Stripe Connect
• Cuenta cerrada: El banco puede haber cerrado la cuenta
• Restricciones del banco: Algunos bancos rechazan transferencias internacionales

Qué hacer:

1. Revisa la notificación in-app con el código de error
2. Actualiza tu información bancaria en Stripe Connect
3. Stripe reintentará automáticamente el payout en el siguiente ciclo
4. Si persiste, contacta soporte para investigación manual

Problema: El pago al banco falló

Posibles causas:

• Error temporal del banco: El banco del experto no pudo procesar el depósito
• Datos bancarios incorrectos: IBAN o datos de cuenta erróneos
• Cuenta con restricciones: La cuenta bancaria tiene límites o bloqueos

Qué hacer:

1. Verifica tu información bancaria en Stripe Connect (Dashboard → Configuración → Pagos)
2. Stripe reintentará el payout automáticamente
3. Si falla múltiples veces, Stripe puede pausar los payouts hasta resolver el problema
4. Contacta soporte si no recibes el pago en 14 días hábiles

Mejores Prácticas

Para Empresas

1. Revisa entregas cuidadosamente: Aprobar solo cuando estés satisfecho
2. Comunícate claramente: Evita malentendidos sobre entregables
3. Aproba rápidamente: Los expertos dependen de los pagos
4. Sé específico al rechazar: Explica qué cambiar

Para Expertos

1. Configura Stripe Connect antes de aceptar proyectos
2. Entrega trabajo de calidad: Evita rechazos
3. Comunícate proactivamente: Resuelve dudas antes de entregar
4. Verifica pagos regularmente: Asegúrate de recibir todo

Resumen de Flujo Completo

1. Empresa acepta propuesta
   → PaymentIntent creado (pending)

2. Stripe autoriza fondos
   → Estado: held

3. Experto sube entrega
   → Estado: held (sin liberar)

4. Empresa aprueba entrega
   → Captura inmediata → Estado: released
   → Intento de transferencia a Connect del experto

5. Si saldo disponible → Transferencia exitosa
   → payout_status: transferred → 2-7 días hábiles a cuenta bancaria

5a. Si saldo NO disponible (fondos pendientes de settlement)
   → payout_status: pending → Scheduler diario reintenta
   → Cuando hay saldo → Transferencia exitosa → 2-7 días hábiles

6. Payout automático → cuenta bancaria del experto
   → El payout agrega múltiples transferencias
   → 2-7 días hábiles adicionales

:::info Transferencia y Payout son automáticos Los pasos 5/5a y 6 son automáticos. El experto no necesita realizar ninguna acción manual. El scheduler gestiona reintentos cuando los fondos no están disponibles inmediatamente. :::

Próximos Pasos

• Guía de Empresa - Flujo completo de proyecto
• Guía de Experto - Flujo completo de experto
• Integración Stripe - Documentación técnica de Stripe