# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qentaz.com/documentation/dispersiones/generar-dispersion.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.