Balances y dispersiones

Esta página cubre Dispersiones y Movimientos. Además de lo que se lista acá, cualquiera de estos endpoints puede devolver los errores comunes. 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 · Listar dispersiones · Detalle · Cancelar · Saldo · Balances · Movimientos · Detalle de movimiento · Dispersar el saldo Todas las rutas de /cashouts responden 403 con {"message": "Company does not have this feature."} si tu empresa no tiene activas las dispersiones.

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.

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.

Dispersiones

Crear una dispersión

POST /cashouts · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10003` `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` `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` `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` `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` `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` `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` `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` `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` `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

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` `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

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `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

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `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` `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` `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 Este endpoint no tiene errores propios. Solo aplican los errores comunes.

Listar balances

GET /wallets · Referencia Este endpoint no tiene errores propios. Solo aplican los errores comunes.

Listar movimientos

GET /transactions · Referencia

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

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `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

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10003` `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` `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` `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` `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` `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` `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` `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

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Dispersiones

Crear una dispersión

Listar dispersiones

Detalle de una dispersión

Cancelar una dispersión

Movimientos

Saldo de la empresa

Listar balances

Listar movimientos

Detalle de un movimiento

Dispersar el saldo a tu cuenta

​Dispersiones

​Crear una dispersión

​Listar dispersiones

​Detalle de una dispersión

​Cancelar una dispersión

​Movimientos

​Saldo de la empresa

​Listar balances

​Listar movimientos

​Detalle de un movimiento

​Dispersar el saldo a tu cuenta

Dispersiones

Crear una dispersión

Listar dispersiones

Detalle de una dispersión

Cancelar una dispersión

Movimientos

Saldo de la empresa

Listar balances

Listar movimientos

Detalle de un movimiento

Dispersar el saldo a tu cuenta