Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Eventos de dispersiones

En estos eventos te notificaremos cada vez que ocurra un cambio de estado en tus dispersiones a terceros. Los estados que se notifican son los siguientes:

event.status
Descripción
detail.status

success

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)

SUCCESS Exitosa

confirm

Caso equivalente a success para dispersiones con autorización por token: se dispara al confirmarse la dispersión con el token recibido.

SUCCESS Exitosa

failed

Cuando la dispersión no pudo completarse.

FAILED Fallida

cancel

Cuando la dispersión fue cancelada.

CANCELED Cancelada

edit

Cuando la dispersión fue modificada. Este evento no corresponde a un estado de la dispersión, por lo que detail.status puede llegar con cualquier valor.

-

Encabezado

Nombre
Contenido

Authorization

Bearer {integration_key}

X-Trazo-Signature

timestamp={timestamp},signature={firma}

X-Trazo-Event-Id

Identificador único del evento

X-Trazo-Event-Attempt

Número de intento: 1, 2 o 3

Content-Type

application/json

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.

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.

Payload

{
    "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
            }
        }
    }
}

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

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.

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.

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

Última actualización