# Actualizar dispersión

Modifica o habilita una dispersión previamente creada. Únicamente aplica para dispersiones que se encuentre en un estado de programadas `scheduled` o que estén en `created` sin que hayan sido confirmadas.

##  Ruta

<mark style="color:purple;">`PATCH`</mark> `/v1/merchant/payout/{external_reference}`

## Encabezado

| Name                                                   | Value            |
| ------------------------------------------------------ | ---------------- |
| `Content-Type`                                         | application/json |
| `x-auth-token`*<mark style="color:red;">**\***</mark>* | {token}          |
| `child-id`                                             | {business\_id}   |

## Cuerpo

Al actualizar esta dispersión, puedes completar o cambiar únicamente los siguientes campos. Ten en cuenta que los nuevos valores reemplazarán los anteriores, por lo que se perderá la información anterior.

{% hint style="warning" %}
Es importante destacar que los bloques d&#x65;*`receiver`* y *`bank_account`* deben ser modificados en su totalidad. Es decir, que si quieres cambiar&#x20;
{% endhint %}

<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></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></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></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></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></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 opcional. 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 opcional. 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 opcional. 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
{
    "message": "The dispersion has been successfully updated.",
    "external_reference": "c5f37bfe",
    "updated_at": "2024-08-27T11:19:07-05: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 %}
{% endtabs %}

***

## **Ejemplo**

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

```bash
curl --location --request PATCH '{{base_url}}/v1/merchant/payout/{{reference}}' \
--header 'x-auth-token: token' \
--data-raw '{
    "currency": "cop",
    "amount": 25000,
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "description": "Descripción modificar disersión",
    "channel": "email",
    "type": "instant",
    "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"
    },
    "attachment": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR_mjlJSi59UFzIXqBbRtRu0Qm2vGSaljlF_A&s"
}'
```

{% endtab %}

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

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

let data = JSON.stringify({
  "status": "CANCELED",
  "amount": "20000.00",
  "channel": "EMAIL",
  "type": "payout",
  "currency": "COP",
  "description": "PRUEBA",
  "reference_one": "Referencia 1",
  "reference_two": "Referencia 2",
  "reference_three": "Referencia 3",
  "reference_four": "Referencia 4",
  "merchant_phone": null,
  "merchant_email": "dev-prueba@qentaz.com",
  "receiver": {
    "phone": "573112222333",
    "email": "diego@trazo.com",
    "first_name": "DIEGO",
    "last_name": "PEREZ",
    "id_type": "CC",
    "id_number": "12345678999"
  },
  "bank_account": {
    "entity": "Banco De Occidente",
    "type": "SAVINGS",
    "number": "9876543210",
    "reference": null
  },
  "approval": {
    "name": " ",
    "method": "TOKEN",
    "date": null
  },
  "updated_at": "2024-08-27T20:02:59.928Z"
});

let config = {
  method: 'patch',
  maxBodyLength: Infinity,
  url: `${base_url}/v1/merchant/payout/${reference}`,
  headers: { 
    'x-auth-token': token
  },
  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/{reference}"

payload = json.dumps({
  "status": "CANCELED",
  "amount": "20000.00",
  "channel": "EMAIL",
  "type": "payout",
  "currency": "COP",
  "description": "PRUEBA",
  "reference_one": "Referencia 1",
  "reference_two": "Referencia 2",
  "reference_three": "Referencia 3",
  "reference_four": "Referencia 4",
  "merchant_phone": None,
  "merchant_email": "dev-prueba@qentaz.com",
  "receiver": {
    "phone": "573112222333",
    "email": "diego@trazo.com",
    "first_name": "DIEGO",
    "last_name": "PEREZ",
    "id_type": "CC",
    "id_number": "12345678999"
  },
  "bank_account": {
    "entity": "Banco De Occidente",
    "type": "SAVINGS",
    "number": "9876543210",
    "reference": None
  },
  "approval": {
    "name": " ",
    "method": "TOKEN",
    "date": None
  },
  "updated_at": "2024-08-27T20:02:59.928Z"
})

headers = {
  'x-auth-token': token
}

response = requests.request("PATCH", 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/actualizar-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.