> 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/dispersiones/generar-dispersion.md).

# Generar dispersión

Realiza dispersiones a tus clientes, proveedores o colaboradores con la información que consideres necesaria, el canal de comunicación que desees usar y el tipo de dispersión que corresponda. A continuación encontrarás todos los parámetros necesarios para la generación de dispersiones.

{% hint style="success" %}
Las opciones de edición dependen del estado y del método de aprobación. [Actualizar dispersión](https://docs.qentaz.com/documentation/dispersiones/actualizar-dispersion.md).
{% endhint %}

## Ruta

<mark style="color:green;">`POST`</mark> `/v1/merchant/payout`

## Encabezado

<table><thead><tr><th width="237">Name</th><th width="135">Type<select><option value="09qFNvjg9CGB" label="string" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>x-auth-token</code><mark style="color:red;">*</mark></td><td><span data-option="09qFNvjg9CGB">string</span></td><td><p>Es el código generado a partir del proceso de autenticación.</p><p><em><code>Ejemplo: 8dsa819dj736f1d87fdhd172f12ddw</code></em></p></td></tr><tr><td><code>Content-Type</code><mark style="color:red;">*</mark></td><td><span data-option="09qFNvjg9CGB">string</span></td><td><p>Es el tipo de contenido que se está enviando en la solicitud.</p><p><em><code>Ejemplo: application/json</code></em></p></td></tr><tr><td><code>child-id</code></td><td><span data-option="09qFNvjg9CGB">string</span></td><td>Es el código de la cuenta que se busca administrar. Es opcional. Más info en el <a href="https://docs.qentaz.com/documentation/cobros/terminos-de-relevancia.md#user-content-guia-de-uso-paso-a-paso-operar-en-nombre-de-una-cuenta-administrada">link</a><br><em><code>Ejemplo: negociohijo</code></em></td></tr></tbody></table>

## Cuerpo

<table><thead><tr><th width="239">Name</th><th width="135">Type<select><option value="avSmkUGK47sr" label="string" color="blue"></option><option value="YWOCFwbFeWek" label="numeric" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>currency</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td>Código que identifica la divisa del pago en formato ISO 4217.<br><br><mark style="color:green;"><code>COP | USD</code></mark></td></tr><tr><td><code>amount</code><mark style="color:red;">*</mark></td><td><span data-option="YWOCFwbFeWek">numeric</span></td><td><p>Valor de la dispersión. No incluir decimales (comas o puntos).</p><p><em><mark style="color:blue;"><code>Ejemplo: 54000</code></mark></em></p></td></tr><tr><td><code>description</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Hace referencia a la descripción de la dispersión. Máximo 200 caracteres.</p><p><em><mark style="color:blue;"><code>Ejemplo: Caja de chocolates x12 unidades, sabores variados.</code></mark></em></p></td></tr><tr><td><code>reference_one</code><br><br><code>reference_two</code><br><br><code>reference_three</code><br><br><code>reference_four</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Información adicional de la dispersión (número de factura, ordenes de compra, categoría), visible para los usuarios.<br></p><p><em><mark style="color:blue;"><code>Ejemplo: FT-2034</code></mark></em></p></td></tr><tr><td><code>channel</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Es la forma como se notifica al usuario de la dispersión.</p><p><mark style="color:green;"><code>whatsapp | email | none</code></mark></p></td></tr><tr><td><code>additional_channel</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td>Es un canal adicional para notificar al usuario de la dispersión.<br><br><mark style="color:green;"><code>whatsapp | email | none</code></mark></td></tr><tr><td><code>additional_channel_value</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td>El número de celular o correo electrónico según el <code>additional_channel</code> que se haya escogido.<br><br><em>Obligatorio si existe additional_channel.</em></td></tr><tr><td><code>type</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Es el método que se usará para la dispersión.</p><p><mark style="color:green;"><code>NORMAL | INSTANT</code></mark></p></td></tr><tr><td><code>attachment</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td>Adjunto que funciona como soporte de la dispersión.</td></tr></tbody></table>

***

### **Información cliente/receptor**

El objeto **receiver** es obligatorio. Cuenta con los siguientes campos:

<table><thead><tr><th width="239">Name</th><th width="135">Type<select><option value="avSmkUGK47sr" label="string" color="blue"></option><option value="YWOCFwbFeWek" label="numeric" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>receiver.phone</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Número de celular del destinatario (incluir el código de área del país)<br></p><p><em><mark style="color:blue;"><code>Ejemplo: 573112223333</code></mark></em></p><p><em>Obligatorio si channel es whatsapp</em> o <em>none.</em></p></td></tr><tr><td><code>receiver.email</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Correo del destinatario al que se enviarán las notificaciones.<br></p><p><em><mark style="color:blue;"><code>Ejemplo: cliente@minegocio.com</code></mark></em></p><p><em>Obligatorio si channel es email</em> o <em>si no existe receiver.phone.</em></p></td></tr><tr><td><code>receiver.first_name</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td>Nombres del destinatario.<br><br><em><mark style="color:blue;"><code>Ejemplo: Andrés</code></mark></em></td></tr><tr><td><code>receiver.last_name</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Apellidos del destinatario.<br></p><p><em><mark style="color:blue;"><code>Ejemplo: Ramírez</code></mark></em></p></td></tr><tr><td><code>receiver.id_type</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Tipo de documento de identificación del destinatario.<br></p><p><mark style="color:green;"><code>CC | CE | NIT | PASAPORTE | DNI | EIN</code></mark></p></td></tr><tr><td><code>receiver.id_number</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Número del documento de identificación del destinatario.</p><p><em><mark style="color:blue;"><code>Ejemplo: 11119999</code></mark></em></p></td></tr></tbody></table>

### Información del aprobador

El objeto `approval` es obligatorio. Para crear dispersiones masivas, usa `POST /v1/merchant/payout/batch`. Envía los movimientos en `dispersions` y un único objeto `approval` al nivel raíz. Conserva el `process_id` común de los movimientos incluidos en `success.data` y revisa `errors.data` para los que no se crearon.

<table><thead><tr><th width="239">Name</th><th width="135">Type<select><option value="avSmkUGK47sr" label="string" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>approval.type</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Método para aprobar las dispersiones.</p><p><mark style="color:green;"><code>NONE | MESSAGE | OTP | TOKEN</code></mark></p><p><em><mark style="color:blue;"><code>Ejemplo: MESSAGE</code></mark></em></p></td></tr><tr><td><code>approval.email</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Correo registrado del aprobador. Para <code>MESSAGE</code> debe tener un correo donde recibir el enlace. Para <code>OTP</code> puedes usar este campo para identificar al aprobador.</p><p><em><mark style="color:blue;"><code>Ejemplo: aprobador@example.com</code></mark></em></p></td></tr><tr><td><code>approval.phone</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Teléfono registrado del aprobador para identificarlo en <code>OTP</code>. Incluye el indicativo del país sin <code>+</code>.</p><p><em><mark style="color:blue;"><code>Ejemplo: 573001234567</code></mark></em></p></td></tr></tbody></table>

Para `NONE` y `TOKEN`, envía únicamente el método, por ejemplo `"approval": { "type": "TOKEN" }`. Para `MESSAGE` y `OTP`, indica también el correo o teléfono del aprobador registrado. [Métodos de confirmación](https://docs.qentaz.com/documentation/dispersiones/terminos-de-relevancia.md#tipos-de-autorizacion).

### **Información del banco receptor**

El objeto **bank\_account** es obligatorio. Cuenta con los siguientes campos:

<table><thead><tr><th width="239">Name</th><th width="135">Type<select><option value="avSmkUGK47sr" label="string" color="blue"></option><option value="YWOCFwbFeWek" label="numeric" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>bank_account.entity</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Código que identifica a la entidad bancaria del destinatario. Ver cómo <a href="https://docs.qentaz.com/documentation/dispersiones/generar-dispersion/consultar-entidades-bancarias.md">consultar códigos</a>.</p><p><em><mark style="color:blue;"><code>Ejemplo: 1007</code></mark></em></p></td></tr><tr><td><code>bank_account.type</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Tipo de cuenta a la que se va realizar la dispersión.<br><br><mark style="color:green;"><code>savings | checking | agreement</code></mark></p><p><strong>[savings = ahorros</strong><br><strong>checking = corriente</strong><br><strong>agreement = convenio]</strong></p></td></tr><tr><td><code>bank_account.number</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Número de cuenta a la que se va realizar la dispersión.</p><p><em><mark style="color:blue;"><code>Ejemplo: 123456789</code></mark></em></p></td></tr><tr><td><code>bank_account.reference</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td>Referencia adicional para el pago en la entidad bancaria. Aplica únicamente para <code>agreement</code>.</td></tr></tbody></table>

## **Respuesta**

{% tabs %}
{% tab title="200" %}

```json
{
    "external_reference": "c5f37bfe",
    "process_id": "eca33e56-3772-4f63-b7a0-0f1c65c6fffc",
    "channel": "EMAIL",
    "type": "NORMAL",
    "approval": "TOKEN",
    "approval_delivery": {
      "status": "sent",
      "event_id": "evento_de_ejemplo",
      "expires_at": "2026-11-10T14:30:00-05:00"
    },
    "created_at": "2024-08-27T14:25:32+00:00"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "Invalid user_id_number or user_id_type provided. Please check the provided details and try again."
}
```

{% endtab %}

{% tab title="401" %}

```bash
{
    "status": "unauthorized",
    "code": "Q103",
    "error": "El x-auth-token se encuentra vencido. Por favor genera un nuevo token y reintenta de nuevo el cobro."
}
```

{% endtab %}
{% endtabs %}

***

### Qué hacer después de crear la dispersión

Guarda el `process_id` de la respuesta. Con `NONE`, aprueba desde **Mis dispersiones** en el Dashboard. Con `MESSAGE`, `OTP` o `TOKEN`, la respuesta incluye `approval_delivery`, que indica si Trazo pudo enviar el enlace, código o token. Revisa su campo `status`:

* **`sent`**. Continúa con el [método de confirmación que elegiste](https://docs.qentaz.com/documentation/dispersiones/terminos-de-relevancia.md#tipos-de-autorizacion). El envío del enlace, código o token todavía no confirma la dispersión.
* **`error`**. La dispersión ya se creó. Usa el mismo `process_id`, revisa `approval_delivery.code` y consulta cómo [solicitar o reenviar la aprobación](https://docs.qentaz.com/documentation/dispersiones/confirmar-dispersion-token.md#solicitar-o-reenviar-la-aprobacion).

Con `TOKEN`, puede ocurrir que tu webhook reciba la autorización pero la respuesta de recepción no llegue a Trazo. En ese caso se devuelve `WEBHOOK_DELIVERY_UNCERTAIN`. Comprueba si recibiste el evento antes de pedir otro envío y usa `approval_delivery.event_id` para identificarlo.

Si habilitaste `payout.created`, Trazo envía un webhook por cada dispersión que se guardó, incluso si sigue pendiente de aprobación. [Eventos de dispersiones](https://docs.qentaz.com/documentation/webhooks/eventos-de-dispersiones.md#creacion-y-aprobacion).

## **Ejemplo**

{% tabs %}
{% tab title="cURL" %}

```bash
curl --location '{{base_url}}/v1/merchant/payout/' \
--header 'x-auth-token: {{x_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "currency": "COP",
    "amount": 20000,
    "description": "PRUEBA",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "channel": "email",
    "additional_channel": "whatsapp",
    "additional_channel_value": "573112222333",
    "type": "NORMAL",
    "approval": {
        "type": "TOKEN"
    },
    "receiver": {
        "email": "destinatario@example.com",
        "first_name": "Diego",
        "id_type": "CC",
        "id_number": "12345678999"
    },
    "bank_account": {
        "entity": "1023",
        "type": "SAVINGS",
        "number": "9876543210"
    }
}'
```

{% endtab %}

{% tab title="NodeJS(Axios)" %}

```javascript
const axios = require('axios');

let data = JSON.stringify({
  "currency": "COP",
  "amount": 20000,
  "description": "PRUEBA",
  "reference_one": "Referencia 1",
  "reference_two": "Referencia 2",
  "reference_three": "Referencia 3",
  "reference_four": "Referencia 4",
  "channel": "email",
  "additional_channel": "whatsapp",
  "additional_channel_value": "573112222333",
  "type": "NORMAL",
  "approval": {
    "type": "TOKEN"
  },
  "receiver": {
    "email": "destinatario@example.com",
    "first_name": "Diego",
    "id_type": "CC",
    "id_number": "12345678999"
  },
  "bank_account": {
    "entity": "1023",
    "type": "SAVINGS",
    "number": "9876543210"
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: `${base_url}/v1/merchant/payout/`,
  headers: { 
    'x-auth-token': token,
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = f"{base_url}/v1/merchant/payout/"

payload = {
  "currency": "COP",
  "amount": 20000,
  "description": "PRUEBA",
  "reference_one": "Referencia 1",
  "reference_two": "Referencia 2",
  "reference_three": "Referencia 3",
  "reference_four": "Referencia 4",
  "channel": "email",
  "additional_channel": "whatsapp",
  "additional_channel_value": "573112222333",
  "type": "NORMAL",
  "approval": {
    "type": "TOKEN"
  },
  "receiver": {
    "email": "destinatario@example.com",
    "first_name": "Diego",
    "id_type": "CC",
    "id_number": "12345678999"
  },
  "bank_account": {
    "entity": "1023",
    "type": "SAVINGS",
    "number": "9876543210"
  }
}

response = requests.post(url, headers={'x-auth-token': token}, json=payload)

print(response.text)

```

{% endtab %}
{% endtabs %}
