# Liquidaciones y consolidación

Después de que los clientes pagan, Fluxis procesa los fondos mediante dos pipelines automatizados en el backend: **consolidación** (mover activos desde vaults de pago) y **liquidación** (agrupar transacciones de ledger confirmadas y enviar el neto a sus direcciones configuradas).

## Flujo de alto nivel

```mermaid
flowchart LR
    PR[Payment Request] --> V[Vault Address]
    V --> C[Consolidation]
    C --> LT[Ledger Transaction]
    LT --> S[Settlement Batch]
    S --> ADDR[Your Settlement Address]
```

1. **Pago** — el cliente envía cripto a una dirección vault por solicitud
2. **Consolidación** — trabajos cron agregan pagos completados desde vaults
3. **Confirmación** — las solicitudes de pago alcanzan `confirmed`; se crean transacciones de ledger
4. **Liquidación** — trabajos cron agrupan transacciones y transfieren importes netos a su dirección de liquidación

El monitoreo on-chain se ejecuta hoy en **Polygon**, **Base**, **Avalanche** y **Arbitrum**.

## Consolidación

La consolidación agrupa solicitudes de pago completadas por dirección vault y activo, luego mueve fondos desde wallets vault efímeras hacia wallets de consolidación controladas por Fluxis.

### Programación cron

| Job | Schedule | Purpose |
| --- | -------- | ------- |
| `CONSOLIDATION_AGGREGATION_JOB` | Every 10 minutes | Agrupar solicitudes de pago elegibles por vault + token |
| `CONSOLIDATION_EXECUTION_JOB` | Every 30 minutes | Ejecutar transferencias de consolidación pendientes |

Las solicitudes de pago vinculadas a una consolidación reciben un `consolidation_id` en la base de datos. Este es un paso operativo interno — los comerciantes normalmente observan el resultado a través del estado de la solicitud de pago y registros de transacciones, no directamente por IDs de consolidación.

::::note
Se aplican umbrales mínimos de consolidación (la agregación usa un importe mínimo configurable). Los saldos pequeños pueden permanecer en vaults hasta alcanzar el umbral.
:::::

## Liquidación

La liquidación agrupa **transacciones de ledger confirmadas** por cuenta, organización y token, luego envía el neto a direcciones de liquidación configuradas.

### Programación cron

| Job | Schedule | Purpose |
| --- | -------- | ------- |
| `SETTLEMENT_AGGREGATION_JOB` | Hourly at `:00` | Agrupar transacciones no liquidadas en registros de liquidación |
| `SETTLEMENT_EXECUTION_JOB` | Hourly at `:05` | Procesar liquidaciones pendientes (transferencias on-chain) |
| `SETTLEMENT_CONFIRMATION_JOB` | Hourly at `:15` | Confirmar transacciones de liquidación on-chain |

### Estados de liquidación

| Status | Meaning |
| ------ | ------- |
| `created` | Registro de liquidación creado |
| `pending` | Listo para ejecución |
| `processing` | Transferencia en curso |
| `completed` | Fondos entregados |
| `failed` | Ejecución fallida |
| `in_review` | Revisión manual requerida |

Si no hay dirección de liquidación configurada para la cuenta (o su organización padre) en la red requerida, la agregación registra un error y omite ese lote.

## Direcciones de liquidación

Las direcciones de liquidación indican a Fluxis **dónde enviar su neto** por red blockchain. Orden de resolución:

1. **Dirección a nivel de cuenta** para la red (si está configurada)
2. **Dirección a nivel de organización** para la red (predeterminado de respaldo)

### REST API — alcance de organización

Las claves API de organización pueden gestionar direcciones directamente:

| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/v1/organization/settlement-addresses` | Listar direcciones de organización |
| POST | `/v1/organization/settlement-addresses` | Crear dirección para una red |
| PUT | `/v1/organization/settlement-addresses` | Actualizar dirección para una red |
| DELETE | `/v1/organization/settlement-addresses?network=polygon` | Eliminar dirección para una red |

Cuerpo de solicitud (POST/PUT):

```json
{
  "network": "polygon",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "address_tag": null
}
```

### REST API — alcance de cuenta

```
GET /v1/account/{accountId}/settlement-addresses
```

Devuelve direcciones de liquidación efectivas para la cuenta (incluyendo respaldos de organización). Los endpoints de crear/actualizar/eliminar a nivel de cuenta existen en el código pero **no están expuestos actualmente** en la API pública — configure sobrescrituras específicas de cuenta a través del Fluxis Dashboard o contacte a soporte.

### Campos de respuesta

| Field | Description |
| ----- | ----------- |
| `owner` | `organization` o `account` |
| `settlement_type` | Categoría de tarifa (p. ej. `payment_net_amount`, `payment_service_fee`) |
| `settlement_address` | Dirección blockchain de destino |
| `address_type` | Identificador de red (p. ej. `polygon`, `base`) |
| `address_tag` | Memo/tag opcional para redes admitidas |

### Dashboard

Las direcciones de liquidación de cuenta también pueden gestionarse en el Fluxis Dashboard en la configuración de cuenta (sección de direcciones de liquidación).

## Ítems de liquidación

Cada liquidación puede contener múltiples **items** que representan divisiones de tarifas:

- Importe neto al comerciante (`payment_net_amount`)
- Tarifas de servicio (`payment_service_fee`)
- Tarifas de desarrollador (`payment_developer_fee`)
- Tarifas de revenue share (`payment_revenue_shared_fee`)

Cada ítem se mapea a una dirección de liquidación del tipo correspondiente cuando está configurada.

## Qué deben configurar los comerciantes

1. **Direcciones de liquidación de organización** — como mínimo, una dirección por red que acepte (Polygon, Base, Avalanche, Arbitrum)
2. **Sobrescrituras de cuenta** (opcional) — destinos por cuenta cuando subcomerciantes necesiten pagos separados
3. **Webhook + conciliación de transacciones** — la liquidación es asíncrona; use [Webhook Events](/es/docs/developers/webhook-events) y [Transactions](/es/docs/developers/transactions) para rastrear la confirmación de pago antes de esperar la liquidación

::::warning
La ejecución de liquidación depende de direcciones válidas para cada red y tipo de ítem. Las direcciones faltantes bloquean la liquidación de los lotes afectados — configure direcciones antes de entrar en producción.
:::::

## Relación con solicitudes de pago

| Payment request status | Consolidation | Settlement |
| ---------------------- | ------------- | ---------- |
| `completed` / `overpaid` / `underpaid` | Elegible tras procesamiento | Tras `confirmed` + transacción de ledger |
| `confirmed` | Puede estar ya consolidado | Elegible para agregación de liquidación |
| `expired` / `failed` | No elegible | No elegible |

## Documentación relacionada

- [Payment Requests](/es/docs/key-concepts/payment-request) — ciclo de vida de estados hasta `confirmed`
- [Transactions](/es/docs/developers/transactions) — registros de ledger que alimentan la liquidación
- [API Integration Guide](/es/docs/developers/tutorials/api-integration-guide) — Paso 4 configuración de liquidación
- [About Fluxis](/es/docs/introduction/about) — redes admitidas y alcance de liquidación