> ## 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.

# Dispersiones

## Posibles eventos

Eventos disponibles para la dispersión.

* `cashout.created`
* `cashout.completed`
* `cashout.processing`
* `cashout.cancelled`
* `cashout.rejected`
* `cashout.require_approval`

## Posibles estados de la transferencia

* `scheduled`
* `to_process`
* `processing`
* `processed`
* `failed`
* `cancelled`
* `turbo_onboarding`

## Diagrama de estados.

```mermaid theme={null}
stateDiagram-v2
    [*] --> scheduled: Creación
    [*] --> to_process: Creación
    scheduled --> to_process: Programado para proceso
    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 --> [*]
```

## Ejemplo

```json theme={null}
{
   "cashout":{
     "id":"99a337b3-3a7d-4e0b-b5ea-7098b562d4dd",
     "customer_id": "4bbd4a30-a29a-4fec-be47-ec2dcf49ebe8",
     "account_id": "e5b15794-5b36-4c41-9c8f-d7cd4c8602cc",
     "is_test": true,
     "amount": 180000,
     "status": "to_process",
     "scheduled_at": "2024-08-17T15:42:12.000000Z",
     "created_at": "2024-08-15T12:12:32.000000Z",
     "external_id":"814",
     "description":"Pago de nómina",
     "reference":"PAYROLL-2391",
     "method":"ACH",
     "discount_to_destination": false,
     "commissions":[
        { "type":"PAYOUT_COMMISSION", "amount":1500.5 },
        { "type":"PAYOUT_SAAS", "amount":2000.25 }
     ],
     "total_commissions":3500.75
   },
   "event":{
      "type":"cashout.created",
      "timestamp":1689262934,
      "environment":"live|test"
   }
}
```

## Cómo casar el evento con tu solicitud

El `id` del payload es el mismo que devuelve el endpoint que originó la dispersión, así que la
conciliación es directa contra la respuesta que ya guardaste:

| Origen                                    | Endpoint                                           | Qué guardas para casar                      |
| ----------------------------------------- | -------------------------------------------------- | ------------------------------------------- |
| Pago a un cliente o tercero               | [`POST /cashouts`](/client/cashouts/create)        | el `id` de la respuesta, o tu `external_id` |
| Dispersión de tu saldo a tu propia cuenta | [`POST /balances`](/client/movimientos/dispersion) | el `id` de la respuesta, o tu `external_id` |

<Note>
  En las dispersiones a **cuenta propia** (`POST /balances`), el `customer_id` del evento es el
  **ID de tu empresa**, no el de un cliente, y la `reference` siempre llega como
  `Deposito a cuenta propia`.
</Note>

<Warning>
  Hasta agosto de 2026, `POST /balances` respondía `204 No Content`: no devolvía el `id`, y los
  eventos `cashout.*` de esas dispersiones llegaban con un identificador que nunca habías visto.
  Ese endpoint ahora responde `201` con la dispersión creada y acepta `external_id`.
</Warning>

## Campos de conciliación

Todos los eventos `cashout.*` devuelven los tres campos que enviaste al crear la dispersión,
para que puedas cruzar el webhook contra tu sistema sin consultar el detalle:

<ResponseField name="description" type="string | null">
  La `description` que enviaste en la creación. Llega `null` si no la enviaste.
</ResponseField>

<ResponseField name="reference" type="string | null">
  La `reference` que enviaste en la creación. Si no enviaste `reference` pero sí `description`,
  aquí llega el valor de `description`.
</ResponseField>

<ResponseField name="external_id" type="string | null">
  El `external_id` que enviaste en la creación. Llega `null` si no lo enviaste.
</ResponseField>

<Note>
  `description` y `reference` se agregaron al payload en julio de 2026. Si tu integración
  es anterior, los eventos que recibiste antes de esa fecha no los incluyen.
</Note>

## Comisiones

Todos los eventos `cashout.*` incluyen el desglose de las comisiones que cobramos por la
dispersión, junto con su total ya calculado.

<ResponseField name="commissions" type="array">
  Desglose de comisiones. Cada entrada tiene `type` (el concepto cobrado, por ejemplo
  `PAYOUT_COMMISSION` para el procesamiento y `PAYOUT_SAAS` para el método) y `amount`
  en pesos. Llega vacío si la dispersión no generó comisiones.
</ResponseField>

<ResponseField name="total_commissions" type="number">
  La suma de los `amount` de `commissions`, en pesos y redondeada a dos decimales. Es el
  total que descontamos por la dispersión, para que no tengas que sumar el arreglo.
</ResponseField>

<Note>
  `total_commissions` se agregó al payload en julio de 2026. El arreglo `commissions` no
  cambió: el campo nuevo es aditivo y solo evita que tengas que sumarlo tú.
</Note>