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

# Solicitar dispersión

> Solicita la dispersión del balance a una cuenta bancaria registrada de tu empresa.

Dispersa el balance de tu cuenta OnePay a una cuenta bancaria registrada de tu empresa.

<Warning>
  **Cambio de contrato (agosto de 2026).** Este endpoint respondía `204 No Content`. Ahora responde
  `201` con la dispersión creada, para que tengas el `id` con el que casar los webhooks
  [`cashout.*`](/client/webhooks/cashouts). Si tu integración valida el status exacto `204`,
  actualízala antes de la fecha de despliegue.
</Warning>

Ambos parámetros son opcionales:

* Si no envías `amount`, se dispersa el **balance completo**.
* Si no envías `account_id`, se usa la **cuenta bancaria principal** (fundable) de tu empresa.

<Note>
  La cuenta bancaria debe pertenecer directamente a tu empresa. Cuentas de tipo PSE no son elegibles como cuenta principal.
  Si envías un `account_id` que pertenece a un cliente o invitado, recibirás un error `company_account_not_found`.
</Note>

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="amount" type="number" placeholder="500000">
  Monto a dispersar en pesos (COP). Mínimo \$10.000. Si no se envía, se dispersa el balance completo.
</ParamField>

<ParamField body="account_id" type="string" placeholder="84cc072e-90e8-33cf-9305-098095fed32f">
  ID de la cuenta bancaria destino. Debe pertenecer a tu empresa (no a un cliente o invitado). Si no se envía, se usa la cuenta principal. [Aprende a registrar cuentas](/client/accounts/create).
</ParamField>

<ParamField body="external_id" type="string" placeholder="TESORERIA-2026-08-19">
  Identificador propio de la dispersión, máximo 100 caracteres. Se devuelve en la respuesta y en
  todos los webhooks `cashout.*` de esta dispersión, para que puedas cruzarla contra tu sistema.
</ParamField>

### Ejemplos de uso

<Tabs>
  <Tab title="Balance completo">
    ```bash theme={null}
    curl https://api.onepay.la/v1/balances \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab title="Monto específico">
    ```bash theme={null}
    curl https://api.onepay.la/v1/balances \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -d '{"amount": 500000}'
    ```
  </Tab>

  <Tab title="Cuenta específica">
    ```bash theme={null}
    curl https://api.onepay.la/v1/balances \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -d '{"amount": 500000, "account_id": "84cc072e-90e8-33cf-9305-098095fed32f"}'
    ```
  </Tab>

  <Tab title="Con external_id">
    ```bash theme={null}
    curl https://api.onepay.la/v1/balances \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -d '{"amount": 500000, "external_id": "TESORERIA-2026-08-19"}'
    ```
  </Tab>
</Tabs>

### Response

La respuesta es la línea de dispersión creada, con las mismas llaves que viajan después en los
webhooks [`cashout.*`](/client/webhooks/cashouts). Guarda el `id` (o envía tu propio `external_id`)
para poder casar esos eventos con la solicitud que hiciste.

<ResponseField name="id" type="string">
  Identificador único de la dispersión. Es el mismo `id` que llega en los webhooks `cashout.*`.
</ResponseField>

<ResponseField name="customer_id" type="string">
  En esta dispersión es el **ID de tu empresa**, porque el dinero va a una cuenta propia y no a un
  cliente. En [`POST /cashouts`](/client/cashouts/create) en cambio es el cliente beneficiario.
</ResponseField>

<ResponseField name="account_id" type="string">
  Cuenta bancaria de tu empresa a la que se envió el dinero.
</ResponseField>

<ResponseField name="amount" type="number">
  Monto dispersado en pesos (COP), no en centavos.
</ResponseField>

<ResponseField name="status" type="string">
  Estado inicial de la dispersión (normalmente `to_process`). Su evolución llega por webhook.
</ResponseField>

<ResponseField name="is_test" type="boolean">
  `true` si la dispersión se creó con una llave de pruebas (`sk_test_xxx`).
</ResponseField>

<ResponseField name="scheduled_at" type="date | null">
  Fecha de programación. En esta dispersión siempre llega `null`: se procesa de inmediato.
</ResponseField>

<ResponseField name="description" type="string">
  Concepto de la operación. En dispersiones a cuenta propia siempre es
  `Envío de fondos OnePay a cuenta.`.
</ResponseField>

<ResponseField name="discount_to_destination" type="boolean">
  `true` si las comisiones se descuentan del monto que llega a la cuenta destino.
</ResponseField>

<ResponseField name="method" type="string">
  Canal utilizado (`ACH`, `TURBO`).
</ResponseField>

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

<ResponseField name="reference" type="string">
  Referencia interna de la operación. En dispersiones a cuenta propia siempre es
  `Deposito a cuenta propia`.
</ResponseField>

<ResponseField name="created_at" type="date">
  Fecha de creación del registro.
</ResponseField>

### Errores

| Código | Nombre                      | HTTP | Descripción                                                |
| ------ | --------------------------- | ---- | ---------------------------------------------------------- |
| 10500  | `balance_is_empty`          | 401  | El saldo está vacío                                        |
| 10501  | `insufficient_funds`        | 401  | El monto solicitado supera el balance disponible           |
| 10809  | `company_account_not_found` | 422  | No se encontró cuenta bancaria o no pertenece a tu empresa |

<ResponseExample>
  ```json 201 theme={null}
  {
     "id":"9d44ce43-a227-4566-b107-5a6bc01cbcdf",
     "customer_id":"9b3f1a20-6d51-4a7e-9f2c-1c9f0e4d7b11",
     "account_id":"84cc072e-90e8-33cf-9305-098095fed32f",
     "is_test":false,
     "amount":500000,
     "status":"to_process",
     "scheduled_at":null,
     "created_at":"2026-08-19T14:32:10.000000Z",
     "external_id":"TESORERIA-2026-08-19",
     "description":"Envío de fondos OnePay a cuenta.",
     "reference":"Deposito a cuenta propia",
     "method":"ACH",
     "discount_to_destination":false
  }
  ```

  ```json 401 theme={null}
  {
    "message": "Tu saldo está vacío, necesitas depositar fondos para continuar con la operación.",
    "code": 10500,
    "code_name": "balance_is_empty"
  }
  ```

  ```json 401 theme={null}
  {
    "message": "No tienes fondos suficientes para hacer está operación.",
    "code": 10501,
    "code_name": "insufficient_funds"
  }
  ```

  ```json 422 theme={null}
  {
    "message": "No se encontró una cuenta bancaria registrada. Debes registrar una cuenta bancaria antes de solicitar una dispersión de balance.",
    "code": 10809,
    "code_name": "company_account_not_found"
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>