> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción

> Envía dinero a cuentas bancarias y billeteras digitales de tus clientes.

## ¿Qué es una Dispersión?

Una dispersión (cashout) permite enviar dinero desde tu saldo en OnePay a la cuenta bancaria o billetera digital de un tercero. Es el flujo inverso al cobro: en lugar de recibir dinero, lo envías.

<Note>
  Para cobrar dinero a un cliente, usa [Payments](/client/payments/index) (link de pago) o [Charges](/client/charges/index) (débito directo).
</Note>

## ¿Cuándo usar Dispersiones?

* Pago a proveedores
* Dispersión de nómina
* Reembolsos a clientes
* Pagos de marketplace a vendedores
* Retiros de billetera

## Tipos de dispersión

| Tipo      | Velocidad  | Cobertura                            | Ideal para                                 |
| --------- | ---------- | ------------------------------------ | ------------------------------------------ |
| **Turbo** | 30-120 min | Bancos principales + Nequi/Daviplata | Pagos urgentes, experiencia en tiempo real |
| **ACH**   | 8-36 horas | 28+ entidades financieras            | Pagos masivos, nómina, mayor cobertura     |

## Ejemplo rápido

```bash theme={null}
curl https://api.onepay.la/v1/cashouts \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: disp-001" \
  -d '{
    "customer_id": "CUSTOMER_ID",
    "account_id": "ACCOUNT_ID",
    "amount": 150000,
    "description": "Pago proveedor Enero"
  }'
```

## Tiempos de procesamiento (Turbo)

| Banco           | Operación | Tiempo promedio | Tiempo máximo | Restricciones                                |
| --------------- | --------- | --------------- | ------------- | -------------------------------------------- |
| Bancolombia     | 24/7      | 30 min          | 120 min       |                                              |
| Davivienda      | 24/7      | 30 min          | 120 min       |                                              |
| BBVA            | Lun-Vie   | 60 min          | 180 min       | Solo 6:00 a 19:00                            |
| Daviplata       | 24/7      | 60 min          | 120 min       |                                              |
| Nequi           | 24/7      | 60 min          | 120 min       | Pagos de 10PM a 6AM se procesan a las 6AM    |
| Banco de Bogotá | 24/7      | 60 min          | 120 min       | Pagos de 20:30 a 3:45 se procesan a las 4:00 |
| Grupo Aval      | Lun-Vie   | 60 min          | 120 min       | Solo 6:00 a 17:30                            |

## Estados de una dispersión

```mermaid theme={null}
stateDiagram-v2
    [*] --> scheduled: Creación programada
    [*] --> to_process: Creación inmediata
    scheduled --> to_process: Llega la fecha
    scheduled --> cancelled: Cancelación

    to_process --> processing: Inicio de procesamiento
    to_process --> require_approval: Requiere aprobación
    to_process --> cancelled: Cancelación

    require_approval --> to_process: Aprobado
    require_approval --> cancelled: Rechazado

    processing --> processed: Éxito
    processing --> failed: Error

    processed --> [*]
    failed --> [*]
    cancelled --> [*]
```

| Estado             | Descripción                                      |
| ------------------ | ------------------------------------------------ |
| `scheduled`        | Programada para procesarse en una fecha futura   |
| `to_process`       | Lista para ser procesada                         |
| `require_approval` | Requiere aprobación manual (según configuración) |
| `processing`       | En proceso de transferencia                      |
| `processed`        | Transferencia exitosa                            |
| `failed`           | Error en la transferencia                        |
| `cancelled`        | Cancelada antes de procesarse                    |

## Endpoints

| Método | Endpoint                 | Descripción               |
| ------ | ------------------------ | ------------------------- |
| `POST` | [/cashouts](create)      | Crear dispersión          |
| `GET`  | [/cashouts](list)        | Listar dispersiones       |
| `GET`  | [/cashouts/{id}](detail) | Detalle de una dispersión |