Flujos de negocio

Ciclo de vida de una remesa

            crear remesa                payin.completed
  ┌─────────┐        ┌─────────┐                ┌────────────┐
  │ (quote) │ ─────▶ │ PENDING │ ─────────────▶ │ PROCESSING │
  └─────────┘        └────┬────┘                └─────┬──────┘
                          │ cancel / payin.failed     │
                          ▼                           │ ¿espera receptor?  ──▶ sigue PROCESSING
                    CANCELLED / FAILED                │ ¿requiere review?  ──▶ sigue PROCESSING
                                                      ▼ (auto si no hay retenciones)
                                                ┌──────┐  payout.completed  ┌───────────┐
                                                │ SENT │ ─────────────────▶ │ DELIVERED │
                                                └──┬───┘                    └───────────┘
                                                   │ payout.failed
                                                   ▼
                                                 FAILED

Reglas de avance (en RemittanceService.advanceProcessing):

1. awaitingRecipient (smart link sin elección) → se queda en PROCESSING.
2. requiresReview (alerta AML abierta) → se queda en PROCESSING hasta que un admin apruebe (/admin/remittances/:id/approve) o rechace.
3. Sin retenciones → createPayout en Cashela → SENT.

Cada transición escribe un RemittanceEvent (timeline del cliente) y emite una notificación (puerto Notifier).

Smart Recipient Flow

1. El remitente crea la remesa con smartRecipient: { fullName, phone }.
2. El API genera recipientToken y devuelve recipientLink (WEB_URL/r/<token>); se comparte por WhatsApp.
3. El receptor abre el link (público), ve cuánto recibe y elige banco / wallet / USDT con sus datos.
4. El API revalida el corredor, recalcula la entrega con el método elegido y, si el pago ya se confirmó, dispara el payout inmediatamente.

Orden flexible: la elección puede ocurrir antes o después del pago del remitente — ambos caminos están cubiertos por tests.

KYC / KYB

• Persona: sube documento + selfie + prueba de residencia → cola del backoffice → APPROVED/REJECTED (con nota). Sin KYC aprobado el API rechaza el envío con KYC_REQUIRED.
• Empresa: el registro crea Company con kybStatus=PENDING. Un admin aprueba el KYB; hasta entonces los envíos devuelven KYB_REQUIRED.

Compliance

B2B (empresa → persona)

Mismo POST /remittances, con el JWT de un usuario BUSINESS: la remesa se etiqueta con companyId, el receptor ve el nombre de la empresa en el smart link, y el portal B2B (/b2b/company) agrega el volumen. Mass payouts (lotes) quedan para Fase 6 — batchId ya existe en el esquema.