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

# Balances y dispersiones

> Errores de dispersiones, del saldo de tu empresa y de sus movimientos.

Esta página cubre [Dispersiones](/client/cashouts/index) y [Movimientos](/client/movimientos/balance). Además de lo que se lista acá, cualquiera de estos endpoints puede devolver los [errores comunes](/client/base/errors/common). Los que tienen un ID en la ruta también responden `404 record_not_found` si el ID no es un UUID, y `404 environment_key_mismatch` si el recurso es del otro ambiente.

**Endpoints:** [Crear dispersión](#crear-una-dispersión) · [Listar dispersiones](#listar-dispersiones) · [Detalle](#detalle-de-una-dispersión) · [Cancelar](#cancelar-una-dispersión) · [Saldo](#saldo-de-la-empresa) · [Balances](#listar-balances) · [Movimientos](#listar-movimientos) · [Detalle de movimiento](#detalle-de-un-movimiento) · [Dispersar el saldo](#dispersar-el-saldo-a-tu-cuenta)

Todas las rutas de `/cashouts` responden `403` con `{"message": "Company does not have this feature."}` si tu empresa no tiene activas las dispersiones.

<Note>
  Una dispersión que el banco rechaza no es un error HTTP: se crea bien y después pasa a `failed`
  con el motivo en `remarks`, y te llega el webhook `cashout.rejected`. Los motivos están en
  [Webhooks de dispersiones](/client/webhooks/cashouts#motivos-de-rechazo).
</Note>

<Note>
  Los errores de saldo (`10500` y `10501`) responden con HTTP `401`, no con `402` ni `422`. No los
  trates como un problema de autenticación: decide por `code_name`.
</Note>

## Dispersiones

### Crear una dispersión

`POST /cashouts` · [Referencia](/client/cashouts/create)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10003`<br />`idempotency_error` | 409 | No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency | Falta el header `x-idempotency`. | Envía un valor único por dispersión. | Sí, con el header |
| `10001`<br />`validation_error` | 422 | El campo customer id es obligatorio. | Un campo falta o no es válido: `customer_id` (un cliente tuyo, y con llave de producción no de prueba), `account_id`, `amount` o `currency`. | Revisa `errors` y corrige el cuerpo. | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | La cuenta no pertenece al cliente o no está relacionada. | `account_id` no es del cliente ni está entre sus cuentas relacionadas. | Usa una cuenta del cliente o relaciónala primero. | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | El monto mínimo es COP \$1.000 | `amount` está por debajo del mínimo, supera tu tope por transacción (por defecto COP 500.000.000) o, por Bre-B, supera COP 10.000.000. | Ajusta el monto. | Sí, tras corregir |
| `41006`<br />`customer_account_uncompleted` | 400 | La cuenta bancaria del cliente no está completa, necesita verificar el número de cuenta para hacer transferencias. | La cuenta destino está incompleta o solo sirve para cobrar (PSE). | Completa la cuenta o usa otra cuenta del beneficiario. | Sí, tras corregir |
| `41007`<br />`customer_onepay_balance_destination` | 400 | La cuenta elegida es el saldo OnePay del destinatario, no una cuenta bancaria: la plata se quedaría en OnePay y el destinatario no podría retirarla. Una llave estática o de cobro registrada por OnePay también va a ese saldo. Elige una cuenta bancaria o la llave Bre-B que el destinatario tiene en su banco. | La cuenta destino es el saldo OnePay del beneficiario o una llave Bre-B emitida por OnePay. | Elige una cuenta bancaria externa o la llave Bre-B que el beneficiario tiene en su banco. | Sí, con otra cuenta |
| `41010`<br />`customer_is_restricted` | 422 | El cliente está restringido para realizar transferencias, esto se debe a una alerta de cumplimiento, revisa con el equipo de soporte si requires información adicional | El beneficiario tiene una alerta de cumplimiento. | Escribe a soporte. | No |
| `41015`<br />`duplicate_external_id` | 422 | Ya existe una transferencia con este external\_id. Solo se puede volver a usar si la anterior falló o se canceló. | Ya hay una dispersión vigente con ese `external_id` (cuando tu empresa tiene activa la unicidad de `external_id`). | Consulta la dispersión existente con `filter[external_id]` en vez de crear otra. | No |
| `41003`<br />`total_amount_exceeds_the_balance` | 422 | El monto que deseas enviar incluidas las comisiones excede el saldo disponible en el balance, tu saldo actual es de COP $... y estas enviado incluidas las comisiones COP $... | El monto más las comisiones supera el saldo de tu balance. | Recarga el balance o envía un monto menor. | Sí, tras recargar |
| Sin código | 500 | Server Error | Llegaste a un límite de dispersiones de tu empresa (cantidad o monto diario), u otra dispersión al mismo beneficiario estaba en curso. | No reintentes en bucle. Si fue un límite, pídele a soporte revisarlo; si no, reintenta con espera y el mismo `x-idempotency`. | Sí, con espera |

### Listar dispersiones

`GET /cashouts` · [Referencia](/client/cashouts/list)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| Sin código | 400 | Requested filter(s) \`...\` are not allowed. Allowed filter(s) are \`...\`. | Enviaste un filtro o un orden que no existe. Los órdenes válidos son `created_at`, `processed_at`, `scheduled_at` y `amount`. | Usa solo los filtros y órdenes de la referencia. | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | La fecha 2026-02-30 no existe. | Una fecha de `filter[created_at]`, `filter[processed_at]` o `filter[scheduled_at]` no es válida. El detalle llega en `errors`. | Envía fechas `AAAA-MM-DD`, o ISO 8601 en los filtros `_from` y `_to`. | Sí, tras corregir |
| Sin código | 500 | Server Error | Usaste `filter[amount]`. Hoy ese filtro falla. | Filtra el monto del lado de tu sistema. | No |

### Detalle de una dispersión

`GET /cashouts/{cashout_id}` · [Referencia](/client/cashouts/detail)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, Transferencia no existe | La dispersión no existe, está archivada o es de otra empresa. | Revisa el `cashout_id`. | No |

### Cancelar una dispersión

`DELETE /cashouts/{cashout_id}` · [Referencia](/client/cashouts/delete)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, Transferencia no existe | La dispersión no existe, está archivada o es de otra empresa. | Revisa el `cashout_id`. | No |
| `41002`<br />`cant_be_cancelled` | 422 | No se puede cancelar la transacción | La dispersión ya salió a despacho o terminó. Solo se cancelan las que están en borrador, programadas, por procesar o esperando aprobación. | Consulta su estado: si ya está en proceso o procesada, no se puede cancelar. | No |
| `41009`<br />`cant_be_refund` | 422 | No se puede reembolsar la transferencia | Ya hay una devolución registrada para esa dispersión. | Escribe a soporte con el `cashout_id`. | No |

## Movimientos

### Saldo de la empresa

`GET /balances` · [Referencia](/client/movimientos/balance)

Este endpoint no tiene errores propios. Solo aplican los [errores comunes](/client/base/errors/common).

### Listar balances

`GET /wallets` · [Referencia](/client/movimientos/wallets)

Este endpoint no tiene errores propios. Solo aplican los [errores comunes](/client/base/errors/common).

### Listar movimientos

`GET /transactions` · [Referencia](/client/movimientos/list)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| Sin código | 400 | Requested filter(s) \`...\` are not allowed. Allowed filter(s) are \`type, subtype, confirmed, from, to, wallet\_id\`. | Enviaste un filtro que no existe. | Usa solo los filtros de la lista. | Sí, tras corregir |
| Sin código | 400 | Requested sort(s) \`...\` is not allowed. Allowed sort(s) are \`created\_at, amount\`. | Enviaste un orden que no existe. | Ordena por `created_at` o `amount`. | Sí, tras corregir |
| Sin código | 500 | Server Error | `filter[from]` o `filter[to]` no es una fecha válida, o trae varias fechas separadas por coma. | Envía una sola fecha `AAAA-MM-DD`. | Sí, tras corregir |

### Detalle de un movimiento

`GET /transactions/{transaction_id}` · [Referencia](/client/movimientos/detail)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, Transaction no existe | El movimiento no existe, es de otra empresa o del otro ambiente. | Revisa el `transaction_id` y la llave. | No |

### Dispersar el saldo a tu cuenta

`POST /balances` · [Referencia](/client/movimientos/dispersion)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10003`<br />`idempotency_error` | 409 | No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency | Falta el header `x-idempotency`. | Envía un valor único por dispersión. | Sí, con el header |
| `10001`<br />`validation_error` | 422 | El tamaño de cantidad debe ser de al menos 10000. | `amount` está fuera de 10.000 a 1.000.000.000, `account_id` no es un UUID o `external_id` tiene más de 100 caracteres. | Revisa `errors` y corrige el cuerpo. | Sí, tras corregir |
| `10500`<br />`balance_is_empty` | 401 | Tu saldo está vacío, necesitas depositar fondos para continuar con la operación. | Tu balance está en cero. | Espera a tener saldo. | Sí, con saldo |
| `10501`<br />`insufficient_funds` | 401 | No tienes fondos suficientes para hacer está operación. | `amount` supera tu saldo. Sin `amount`, también puede salir si tu saldo tiene centavos. | Envía un `amount` entero menor o igual a tu saldo. | Sí, con otro monto |
| `10809`<br />`company_account_not_found` | 422 | No se encontró una cuenta bancaria registrada. Debes registrar una cuenta bancaria antes de solicitar una dispersión de balance. | Tu empresa no tiene cuentas propias, o `account_id` no es una cuenta tuya. | Registra una cuenta bancaria o corrige `account_id`. | Sí, tras corregir |
| `10809`<br />`company_account_not_found` | 422 | Ninguna de tus cuentas bancarias está habilitada para recibir dispersiones: el banco rechazó su verificación, está desconectada o su registro está incompleto. Indica en account\_id la cuenta a la que quieres dispersar o registra una nueva. | No enviaste `account_id` y ninguna de tus cuentas está habilitada para dispersiones. | Envía `account_id` o registra una cuenta nueva. | Sí, tras corregir |
| `41013`<br />`daily_cashout_scheduled` | 422 | Tu empresa ya tiene un cashout diario programado, por lo que no puede realizar desembolsos manuales. | Tu empresa tiene activa la dispersión diaria automática. | Espera al ciclo automático o pídele a soporte desactivarlo. | No |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.