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.

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",
     "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:

description · string | null

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

reference · string | null

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

external_id · 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.

commissions · 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.

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