Dispersiones

Posibles eventos

Eventos disponibles para la dispersión.

Evento	Cuándo se emite
`cashout.created`	Al crear la dispersión en `to_process` o `scheduled`, y al aprobarse un borrador del panel. Se emite una sola vez por dispersión: pasar de `scheduled` a `to_process` no lo repite.
`cashout.require_approval`	Al crear la dispersión cuando tu cuenta exige aprobación antes del envío.
`cashout.processing`	Cuando la dispersión se envía al riel de pago.
`cashout.completed`	Cuando el abono al beneficiario se completó.
`cashout.rejected`	Cuando la dispersión falla. El valor vuelve a tu saldo y el motivo llega en `remarks`.
`cashout.cancelled`	Cuando la dispersión se cancela antes de enviarse.

Cada evento incluye el external_id que enviaste al crear la dispersión, en cashout.external_id.

Posibles estados de la transferencia

scheduled
to_process
processing
processed
failed
cancelled
require_approval

Diagrama de estados.

Motivos de rechazo

Cuando una dispersión falla, el objeto cashout trae remarks con el motivo. Mientras no haya motivo, remarks es null.

"remarks": {
  "code": "IDENTIFICATION_FAILED",
  "description": "Identificación del titular no coincide.",
  "customer_description": "El banco rechazó la transferencia porque los datos del documento de identidad no coinciden con los registrados en la cuenta destino.",
  "retryable": false
}

code: identificador estable del motivo. Decide por este campo, no por el texto.
description: texto corto del motivo.
customer_description: explicación para mostrar a tu equipo o al beneficiario.
retryable: true solo si puedes reintentar la misma dispersión tal cual. Con false, hay que corregir algo antes (la cuenta, la llave o el método).

VERIFYING_WITH_NETWORK llega con la dispersión todavía en processing: la red no confirmó si el beneficiario recibió el dinero. No reintentes: podrías desembolsar dos veces. Te avisamos con cashout.completed o cashout.rejected cuando se resuelva.

Verificación de titularidad Bre-B

Antes de cada envío por Bre-B, OnePay consulta la llave en el directorio y confirma que esté activa, que apunte al mismo banco y cuenta y que el documento del titular coincida con el del beneficiario. Si no coincide, la dispersión falla sin que el dinero salga, con uno de estos motivos:

Código	Significado en un envío por Bre-B
`IDENTIFICATION_FAILED`	La llave está a nombre de una persona con otro documento.
`DATA_MISMATCH`	La llave apunta a otro banco o cuenta.
`ACCOUNT_NUMBER_FAILED`	La llave no está activa en el directorio.
`NOT_FOUND_ACCOUNT`	No se encontró una llave Bre-B para la cuenta.

Todos los motivos

Código	Descripción	`retryable`
`NOT_FOUND_ACCOUNT`	Cuenta no encontrada o recientemente cerrada / cancelada.	`false`
`IDENTIFICATION_FAILED`	Identificación del titular no coincide.	`false`
`DATA_MISMATCH`	Cuenta y titular no coinciden.	`false`
`ACCOUNT_NUMBER_FAILED`	Cuenta inactiva o bloqueada.	`false`
`ACCOUNT_NOT_EXIST`	Cuenta no existe.	`false`
`ACCOUNT_CANCELLED`	Cuenta cancelada o cerrada.	`false`
`ACCOUNT_DONT_ALLOW_DEPOSIT`	Cuenta no permite depósitos.	`false`
`BAD_ACCOUNT_TYPE`	Tipo de cuenta errado.	`false`
`BANK_REJECTED`	Pago rechazado por el banco.	`true`
`TRY_AGAIN`	El banco no pudo procesar el pago, intente nuevamente.	`true`
`TRY_IN_ACH`	El banco no completó la transacción; se recomienda enviar por ACH.	`false`
`BANK_NOT_SUPPORTED`	El banco no soporta este movimiento; se recomienda enviar por ACH.	`false`
`PROVIDER_UNDER_CONTINGENCY`	El proveedor está en contingencia; se puede reintentar cuando restablezca el servicio.	`true`
`TRANSACTION_NOT_FOUND`	La red confirmó que el beneficiario no recibió la transferencia.	`true`
`VERIFYING_WITH_NETWORK`	Verificando con la red si el beneficiario recibió.	`false`
`TRANSACTION_LIMIT_BREB`	La transacción excede el límite de monto de Bre-B.	`false`
`COMPANY_TRANSACTION_LIMIT_MAX_AMOUNT`	Excede el monto máximo por transacción de tu empresa.	`false`
`COMPANY_TRANSACTION_LIMIT_AMOUNT`	Excede el límite de monto diario de tu empresa.	`false`
`COMPANY_TRANSACTION_LIMIT_COUNT`	Excede el límite de transacciones diarias de tu empresa.	`false`
`FRAUD_TRANSACTION`	Transacción con sospecha de fraude.	`false`
`TEST_MODE`	Transacción fallida en modo prueba.	`false`
`OTHER`	Motivo desconocido.	`false`

Ejemplo

{
   "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",
     "processed_at": null,
     "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`	el `id` de la respuesta, o tu `external_id`
Dispersión de tu saldo a tu propia cuenta	`POST /balances`	el `id` de la respuesta, o tu `external_id`

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.

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.

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:

string | null

La description que enviaste en la creación. Llega null si no la enviaste.

string | null

La reference que enviaste en la creación. Si no enviaste reference pero sí description, aquí llega el valor de description.

string | null

El external_id que enviaste en la creación. Llega null si no lo enviaste.

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.

Comisiones

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

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.

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.

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

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Posibles eventos

Posibles estados de la transferencia

Diagrama de estados.

Motivos de rechazo

Verificación de titularidad Bre-B

Todos los motivos

Ejemplo

Cómo casar el evento con tu solicitud

Campos de conciliación

Comisiones

​Posibles eventos

​Posibles estados de la transferencia

​Diagrama de estados.

​Motivos de rechazo

​Verificación de titularidad Bre-B

​Todos los motivos

​Ejemplo

​Cómo casar el evento con tu solicitud

​Campos de conciliación

​Comisiones

Posibles eventos

Posibles estados de la transferencia

Diagrama de estados.

Motivos de rechazo

Verificación de titularidad Bre-B

Todos los motivos

Ejemplo

Cómo casar el evento con tu solicitud

Campos de conciliación

Comisiones