> 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-cobros.md).

# Eventos de cobros

En estos eventos, te notificaremos cada vez que ocurra algún cambio de estado en tus cobros, independientemente de si estos se completan por parte del cliente o si se realizan automáticamente por el sistema. Este seguimiento detallado te permitirá estar al tanto de cada fase del proceso de cobro, brindándote la tranquilidad de no perder ninguna actualización importante referente a tus transacciones financieras. Los estados que se notifican son los siguientes:

<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>success</code></td><td>Cuando el pago ha sido completado/pagado.</td><td>SUCCESS<br><code>Exitoso</code></td></tr><tr><td><code>review</code></td><td>Cuando el pago está en revisión (ejemplo: pago en efectivo a un transportador)</td><td>REVIEW<br><code>Por conciliar</code></td></tr><tr><td><code>overdue</code></td><td>Cuando el cobro no fue completado/pagado a tiempo</td><td>OVERDUE<br><code>Vencido</code></td></tr><tr><td><code>failed</code></td><td>Cuando el pago no pudo completarse.</td><td>FAILED<br><code>Fallido</code></td></tr><tr><td><code>blocked</code></td><td>Cuando el pago ha sido bloqueado por sospecha de fraude.</td><td>BLOCKED<br><code>Bloqueado</code></td></tr><tr><td><code>accepted</code></td><td>Cuando el pago fue aceptado por la entidad pero todavía no se acredita.</td><td>ACCEPTED<br><code>Aceptado</code></td></tr><tr><td><code>cancel</code></td><td>Cuando el cobro fue cancelado.</td><td>CANCELED<br><code>Cancelado</code></td></tr><tr><td><code>credit</code></td><td>Cuando el pago se realizó con cupo de crédito.</td><td>CREDIT<br><code>Crédito</code></td></tr><tr><td><code>external</code></td><td>Cuando el pago fue registrado por un medio externo a Trazo.</td><td>SUCCESS<br><code>Exitoso</code></td></tr><tr><td><code>ret_pending</code></td><td>Cuando se inició una devolución del pago.</td><td>RET_PENDING<br><code>Devolución pendiente</code></td></tr><tr><td><code>ret_review</code></td><td>Cuando la devolución está en revisión.</td><td>RET_REVIEW<br><code>Devolución en revisión</code></td></tr><tr><td><code>ret_success</code></td><td>Cuando la devolución se completó.</td><td>RET_SUCCESS<br><code>Devolución exitosa</code></td></tr><tr><td><code>edit</code></td><td>Cuando el cobro fue modificado. Este evento no corresponde a un estado de la transacción, por lo que <code>detail.status</code> puede llegar con cualquier valor.</td><td>-</td></tr></tbody></table>

Esto te permitirá mantener un control efectivo sobre tus cobros y reaccionar rápidamente ante cualquier eventualidad que pueda surgir.

{% hint style="warning" %}
Ten en cuenta que `event.status` y `detail.status` son campos distintos. `event.status` identifica el evento y viaja siempre en minúscula (`success`); `detail.status` es el estado de la transacción y viaja en mayúscula (`SUCCESS`). Si filtras por el evento, usa `event.status` en minúscula.
{% endhint %}

Es importante tener en cuenta que los cobros recibidos en efectivo, y agrupados o consolidados por los cobradores, solo pasarán a ser exitosos en el momento en que se complete la legalización en un punto de recaudo. Cuando esto suceda, se notificará inmediatamente cada uno de los pagos en efectivo asociados a la conciliación.

## 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" %}
Cómo validar la firma, la política de reintentos y el uso del `event_id` para identificar reintentos son iguales para todos los eventos de Trazo: encontrarás el detalle en la [Introducción](/documentation/webhooks/introduccion.md).
{% endhint %}

## Payload

{% code overflow="wrap" %}

```json
{
    "event_id": "22548809-0772-498e-a569-b8330babe76d",
    "event": {
        "type": "payment",
        "status": "success"
    },
    "created_at": "2025-03-15 16:49:02.891",
    "external_reference": "A1A2A3A4",
    "detail": {
        "amount": "29900",
        "currency": "COP",
        "description": "Ejemplo cobro exitoso",
        "reference_one": "REF1",
        "reference_two": "REF2",
        "reference_three": "REF3",
        "reference_four": "REF4",
        "reference_five": "REF5",
        "reference_six": "REF6",
        "reference_seven": "REF7",
        "reference_eight": "REF8",
        "channel": "WHATSAPP",
        "status": "SUCCESS",
        "payment_method": "card",
        "payment_method_source": "amex",
        "process_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "url_receipt": "https://content.qentaz.com/aaaabbbbccccdddd",
        "payer": {
            "phone": "573778889999",
            "email": "test@qentaz.com",
            "first_name": "Nombre",
            "last_name": "Apellido",
            "business_name": "",
            "user_id_type": "CC",
            "user_id_number": "1234567890",
            "user_id_number_dv": null
        },
        "merchant": {
            "name": "Comercio Ejemplo",
            "id_type": "NIT",
            "id_number": "900123456",
            "phone": "573998887777",
            "email": ""
        },
        "invoicing": {
            "provider": null,
            "type": null,
            "invoice_id": null,
            "invoice_number": null,
            "invoice_url": null,
            "voucher": {
                "id": null,
                "number": null
            },
            "credit_note": null,
            "debit_note": null
        }
    }
}
```

{% endcode %}

{% hint style="info" %}
El bloque `invoicing` viaja siempre, aunque el comercio no tenga facturación electrónica configurada — en ese caso llega con sus campos en `null`, como en el ejemplo. Cuando el comercio sí factura vía Trazo, `provider`, `invoice_id` y `voucher.id` se completan con los datos del documento emitido.
{% endhint %}

### Documentos emitidos en el momento del pago

Cuando el comercio factura vía Trazo y el documento se emite junto con la notificación del pago, `voucher` y `credit_note` viajan con el resultado de esa emisión. En ese caso incluyen un campo `status` que no está presente en el ejemplo anterior:

{% code overflow="wrap" %}

```json
"invoicing": {
    "provider": "siigo",
    "type": "link",
    "invoice_id": "aaaabbbb-cccc-dddd-eeee-ffffgggghhhh",
    "invoice_number": "FE-1234",
    "invoice_url": "https://content.qentaz.com/aaaabbbbccccdddd",
    "voucher": {
        "status": "success",
        "id": "11112222-3333-4444-5555-666677778888",
        "number": "RC-560"
    },
    "credit_note": null,
    "debit_note": null
}
```

{% endcode %}

Los valores posibles de `status` son:

<table><thead><tr><th width="134.93359375">Valor</th><th>Descripción</th></tr></thead><tbody><tr><td>success</td><td>El documento se emitió correctamente. id y number traen los datos del documento.</td></tr><tr><td>failed</td><td>El documento no pudo emitirse. id y number llegan en null y se incluye un campo error con el detalle.</td></tr></tbody></table>

{% hint style="info" %}
Cuando el documento no aplica para ese cobro, el campo llega directamente en `null` en lugar de un objeto. Te recomendamos validar que el campo no sea `null` antes de leer sus propiedades.
{% endhint %}

### Detalle del evento de modificación

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

Este evento se dispara únicamente después de que el cambio ya se aplicó. Por eso el conjunto de claves de `detail` varía según qué se haya editado: no es un esquema fijo como en los demás eventos.

{% code overflow="wrap" %}

```json
{
    "event_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "event": {
        "type": "payment",
        "status": "edit"
    },
    "created_at": "2025-03-15 16:49:02.891",
    "external_reference": "A1A2A3A4",
    "detail": {
        "amount": "35000"
    }
} 
```

{% endcode %}