> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/webhooks/eventos-de-dispersiones.md).

# Eventos de dispersiones

Recibe notificaciones al crear y aprobar dispersiones desde la API, y cuando cambia su estado. En los eventos de esta página, `event.type` es `payout`.

<table><thead><tr><th width="153.03515625">event.status</th><th>Descripción</th><th width="215.95703125">detail.status</th></tr></thead><tbody><tr><td><code>created</code></td><td>La API guardó la dispersión. Se puede emitir aunque siga pendiente de aprobación o falle el envío al aprobador.</td><td>Estado al momento de emitir el evento.</td></tr><tr><td><code>approved</code></td><td>La API guardó la aprobación y activó la dispersión para procesarla.</td><td>Estado al momento de emitir el evento. Puede haber avanzado desde <code>PENDING</code>.</td></tr><tr><td><code>success</code></td><td>Cuando la dispersión fue confirmada por la entidad bancaria del destinatario. (*Colombia: esta confirmación puede demorar entre 4 y 6 horas hábiles después de la recepción del dinero, por los ciclos ACH)</td><td>SUCCESS<br><code>Exitosa</code></td></tr><tr><td><code>failed</code></td><td>Cuando la dispersión no pudo completarse.</td><td>FAILED<br><code>Fallida</code></td></tr><tr><td><code>cancel</code></td><td>Cuando la dispersión fue cancelada.</td><td>CANCELED<br><code>Cancelada</code></td></tr><tr><td><code>edit</code></td><td>Cuando la dispersión fue modificada. Este evento no corresponde a un estado de la dispersión, por lo que <code>detail.status</code> puede llegar con cualquier valor.</td><td>-</td></tr></tbody></table>

## Creación y aprobación

En dispersiones masivas, recibirás un evento por cada dispersión guardada. Usa `detail.process_id` para agruparlas y `external_reference` para identificar cada una. Si se reenvía un mismo evento para una referencia, conserva su `event_id`. Usa ese ID para evitar procesarlo dos veces.

`payout.approved` se emite después de guardar la confirmación por API con OTP o token, o por enlace en el Portal. Para saber cuándo se completó el desembolso, usa `payout.success`.

Ejemplo abreviado de `payout.approved`.

```json
{
  "event_id": "f55f2320-9d89-4c88-a9a7-b13bffb386da",
  "event": { "type": "payout", "status": "approved" },
  "created_at": "2026-11-10 19:26:00.000",
  "external_reference": "a1a2a3a4",
  "detail": {
    "amount": "29900",
    "currency": "COP",
    "status": "PENDING",
    "process_id": "eca33e56-3772-4f63-b7a0-0f1c65c6fffc",
    "approver": { "date": "2026-11-10" }
  }
}
```

## Entrega del token de aprobación

Con `approval.type: "TOKEN"`, Trazo envía `payout.approval_requested` al webhook HTTPS del comercio. Esta entrega es parte del flujo de confirmación y funciona independientemente de los eventos que habilites. Usa `process_id` en la raíz del evento y `authorization.token` en la solicitud de confirmación. El vencimiento está en `authorization.expires_at`. [Confirmar dispersión](https://docs.qentaz.com/documentation/dispersiones/confirmar-dispersion-token.md).

## Encabezado

<table><thead><tr><th width="231.90625">Nombre</th><th>Contenido</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Bearer {integration_key}</td></tr><tr><td><code>X-Trazo-Signature</code></td><td>timestamp={timestamp},signature={firma}</td></tr><tr><td><code>X-Trazo-Event-Id</code></td><td>Identificador único del evento</td></tr><tr><td><code>X-Trazo-Event-Attempt</code></td><td>Número de intento: 1, 2 o 3</td></tr><tr><td><code>Content-Type</code></td><td>application/json</td></tr></tbody></table>

Si configuraste un encabezado personalizado para tu comercio, este se envía además de los anteriores con el nombre y el valor que hayas definido.

{% hint style="info" %}
Para conocer más detalles sobre las firmas en los eventos, consulta [Validación de firma](https://docs.qentaz.com/documentation/webhooks/introduccion.md#validacion-de-la-firma). La política de reintentos y el uso del `event_id` se describen en la [Introducción](https://docs.qentaz.com/documentation/webhooks/introduccion.md).
{% endhint %}

## Payload

{% code overflow="wrap" %}

```json
{
    "event_id": "7f3b1c2d-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "event": {
        "type": "payout",
        "status": "success"
    },
    "created_at": "2025-03-15 16:49:02.891",
    "external_reference": "a1a2a3a4",
    "detail": {
        "amount": "29900",
        "currency": "COP",
        "description": "Ejemplo dispersión exitosa",
        "reference_one": "REF1",
        "reference_two": "REF2",
        "reference_three": "REF3",
        "reference_four": "REF4",
        "channel": "WHATSAPP",
        "status": "SUCCESS",
        "payment_method": "manual",
        "payment_method_source": "bancolombia",
        "process_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "url_receipt": "https://content.qentaz.com/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/a1a2a3.pdf",
        "creator": {
            "name": "Comercio Ejemplo",
            "first_name": null,
            "last_name": null,
            "phone": "573998887777",
            "email": "comercio@qentaz.com",
            "id_number": "900123456"
        },
        "approver": {
            "name": null,
            "first_name": "Ana",
            "last_name": "Gomez",
            "id_number": "1122334455",
            "phone": "573887779999",
            "email": "ana@comercioejemplo.com",
            "date": "2025-03-14",
            "signature": "Qentaz.sdamd012fmoci209008120833f9d0129fj10f21=="
        },
        "receiver": {
            "first_name": "Nombre",
            "last_name": "Apellido",
            "business_name": "",
            "id_type": "CC",
            "id_number": "1234567890",
            "id_number_dv": null,
            "phone": "573778889999",
            "email": "test@qentaz.com",
            "bank_name": "Bancolombia",
            "account_number": "12345678",
            "account_type": "SAVINGS"
        },
        "invoicing": {
            "provider": null,
            "type": null,
            "bill_id": null,
            "bill_number": null,
            "voucher": {
                "id": null,
                "number": null
            }
        }
    }
}
```

{% endcode %}

{% hint style="info" %}
`creator` es quien generó la dispersión; `approver` es quien la autorizó. `approver` llega con todos sus campos en `null` cuando la dispersión aún no tiene una aprobación registrada (por ejemplo, mientras está pendiente).
{% endhint %}

{% hint style="info" %}
El bloque `invoicing` viaja siempre, aunque el comercio no tenga facturación electrónica configurada para dispersiones — en ese caso llega con sus campos en `null`, como en el ejemplo.
{% endhint %}

### Detalle del evento de modificación

A diferencia de los demás eventos, en `edit` el objeto `detail` **no** trae la foto completa de la dispersión. Trae únicamente los campos que cambiaron, con su valor nuevo.

{% hint style="info" %}
Este evento se dispara después de que el cambio ya se aplicó, así que no hay forma de incluir el valor anterior del campo — solo reportamos lo que cambió y a qué quedó.
{% endhint %}

{% code overflow="wrap" %}

```json
{
    "event_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "event": {
        "type": "payout",
        "status": "edit"
    },
    "created_at": "2025-03-15 16:49:02.891",
    "external_reference": "a1a2a3a4",
    "detail": {
        "amount": "35000"
    }
}
```

{% endcode %}
