> 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" %}
Existen algunos campos que pueden completarse o modificarse al actualizar una dispersión, es importante tener en cuenta que, únicamente pueden actualizarse las dispersiones en estado `created`.
{% 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="/pages/cmdh7wawmADehdqeF0JP#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></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></p><p><em><mark style="color:blue;"><code>Ejemplo: Caja de chocolates x12 unidades, sabores variados.</code></mark></em></p><p></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></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></p><p><mark style="color:green;"><code>normal | instant | scheduled</code></mark></p><p></p></td></tr><tr><td><code>send_date</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Es la fecha en la que se debe realizar la dispersión programada al destinatario. </p><p><mark style="color:green;"><code>Formato: AAAA/MM/DD</code></mark><br><br><em><mark style="color:blue;"><code>Ejemplo: 2025/01/30</code></mark></em></p><p></p><p><strong>Obligatorio si el status es scheduled</strong></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></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></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></p><p><em><mark style="color:blue;"><code>Ejemplo: 11119999</code></mark></em></p></td></tr></tbody></table>

### **Información del aprovador**

El objeto **approval** 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>approval.type</code><mark style="color:red;">*</mark></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Tipo de autorización definida para la dispersión.</p><p></p><p><mark style="color:green;"><code>none | message | otp</code></mark></p></td></tr><tr><td><code>approval.phone</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Número de celular del usuario que va a aprobar la dispersión (incluir el código de área del país). El usuario debe tener rol admin o coordinator.<br></p><p><em><mark style="color:blue;"><code>Ejemplo: 573112223333</code></mark></em><br><br><em>Obligatorio si el approval.type es message. Solo se debe suministrar el approval.phone o el approval.email.</em></p></td></tr><tr><td><code>approval.email</code></td><td><span data-option="avSmkUGK47sr">string</span></td><td><p>Correo del destinatario que va a aprobar la dispersión. El usuario debe tener rol admin o coordinator.<br></p><p><em><mark style="color:blue;"><code>Ejemplo: cliente@minegocio.com</code></mark></em></p><p></p><p><em>Obligatorio si el approval.type es message. Solo se debe suministrar el approval.phone o el approval.email.</em></p></td></tr></tbody></table>

### **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="/pages/ya0rrn5vhnVPFjLNrju9">consultar códigos</a>.</p><p></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></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></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",
    "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 %}

***

## **Ejemplo**

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

```bash
curl --location '{{base_url}}/v1/merchant/payout/' \
--header 'x-auth-token: token' \
--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": "diego@trazo.com",
        "first_name": "Diego",
        "id_type": "CC",
        "id_number": "12345678999"
    },
    "bank_account": {
        "entity": "1023",
        "type": "savings",
        "number": "9876543210"
    }
}'
```

{% endtab %}

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

<pre class="language-javascript"><code class="lang-javascript">const axios = require('axios');
<strong>
</strong>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": "diego@trazo.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 //Añadir token
  },
  data : data
};

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

</code></pre>

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

payload = json.dumps({
  "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": "diego@trazo.com",
    "first_name": "Diego",
    "id_type": "CC",
    "id_number": "12345678999"
  },
  "bank_account": {
    "entity": "1023",
    "type": "savings",
    "number": "9876543210"
  }
})

headers = {
  'x-auth-token': token #Añadir token
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

```

{% endtab %}
{% endtabs %}