# Generar Cobro

Esta API permite crear y gestionar cobros de manera flexible, adaptándose a diferentes escenarios de pago: creados, programados y normales. Los cobros pueden personalizarse con reglas de vencimiento, recargos, descuentos anticipados y notificaciones automatizadas, garantizando una integración sencilla y escalable para el comercio. **Es esencial que te asegures de generar un único cobro por cada venta, pedido o interacción con el cliente, según sea apropiado.** 

## Ruta

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

## **Encabezado**

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

{% hint style="info" %}
El child-id es opcional y se usa para las cuentas administradas para conocer más puedes ingresa a este [enlace](/documentation/cobros/terminos-de-relevancia.md#cuentas-administradas).
{% endhint %}

## **Cuerpo**&#x20;

### **Información general**

<table><thead><tr><th width="249">Name</th><th width="126">Type<select><option value="GnWreahNlF6F" label="numeric" color="blue"></option><option value="sFwIPm2Dqll0" label="string" color="blue"></option><option value="l8UgNW8hbMuc" label="date" color="blue"></option><option value="VIiuN2CCxiaY" label="boolean" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Es el estado del cobro al momento de creación. <a href="/pages/cmdh7wawmADehdqeF0JP#tipos-de-cobros">Para más información de los estados.</a><br><br><mark style="color:green;"><code>created | pending | scheduled</code></mark></td></tr><tr><td><code>currency</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td><p>Código que identifica la divisa del cobro en formato ISO 4217.<br></p><p><mark style="color:green;"><code>cop | usd</code></mark></p></td></tr><tr><td><code>amount</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="GnWreahNlF6F">numeric</span></td><td><p>Es el importe final que se debe recibir por el producto o servicio ofrecido. Se debe emplear el punto como separador decimal.</p><p></p><p>ℹ️ <em>El monto debe ser mayor a 0.</em></p><p></p><p><em><mark style="color:blue;"><code>Ejemplo: 54000.85</code></mark></em></p></td></tr><tr><td><code>description</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td><p>Proporciona detalles clave sobre el cobro y es lo que se refleja en los comprobantes de pago.</p><p></p><p>ℹ️ <em>La descripción debe contener mínimo 5 caracteres.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: Servicio de entrega</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><br><br><code>reference_five</code><br><br><code>reference_six</code><br><br><code>reference_seven</code><br><br><code>reference_eight</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Información adicional del cobro (número de factura, ordenes de compra, categoría), visible para los usuarios.<br><br><em><mark style="color:blue;"><code>Ejemplo: FAC123</code></mark></em></td></tr><tr><td><code>channel</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td><p>Es el canal por el que se notificará al cliente, bien sea el cobro o el comprobante de pago.</p><p></p><p>ℹ️ <em>Por defecto es enlace de pago (link).</em><br><br><mark style="color:green;"><code>whatsapp | link | email</code></mark></p></td></tr><tr><td><code>user_notification</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td><p>Define si se quiere enviar una notificación del cobro al usuario. Por defecto el valor es <em><strong>true</strong></em>.</p><p></p><p><em>ℹ️ Por defecto es false. Si el channel es link, no se enviará ninguna notificación.</em><br><br><mark style="color:green;"><code>true | false</code></mark></p></td></tr><tr><td><code>expected_amount</code></td><td><span data-option="GnWreahNlF6F">numeric</span></td><td><p>Es el valor esperado del cobro.  Es un valor meramente informativo y no afecta en absoluto el proceso de cobro. </p><p></p><p><em>ℹ️ En caso de no suministrar ningún valor se asignara por defecto el amount.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 10000</code></mark></em></p></td></tr><tr><td><code>expected_date</code></td><td><span data-option="l8UgNW8hbMuc">date</span></td><td>Es la fecha estimada de finalización de la transacción. Es un valor meramente informativo y no afecta en absoluto el proceso de cobro.<br><br><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></td></tr><tr><td><code>reminder_date</code></td><td><span data-option="l8UgNW8hbMuc">date</span></td><td>Corresponde a la fecha en la que quieres activar un cobro programado. Al activarse se envía una notificación al cliente.<br><br><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></td></tr><tr><td><code>limit_date</code></td><td><span data-option="l8UgNW8hbMuc">date</span></td><td><p>Es la fecha en la que vence el cobro para el cliente. </p><p></p><p><em>ℹ️ Si se quieren usar recargos o pagos anticipados, este campo es obligatorio.</em><br><br><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></td></tr><tr><td><code>merchant_id_number</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Número de documento del usuario que genera el cobro.<br><br><em><mark style="color:blue;"><code>Ejemplo: 100110000</code></mark></em></td></tr><tr><td><code>merchant_phone</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Número de celular del usuario que genera el cobro (incluir el código de área del país).<br><br><em><mark style="color:blue;"><code>Ejemplo: 573112229999</code></mark></em></td></tr><tr><td><code>merchant_email</code><em><mark style="color:red;"><strong>*</strong></mark></em></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Correo del usuario que genera el cobro.<br><br><em><mark style="color:blue;"><code>Ejemplo: alguien@ejemplo.com</code></mark></em></td></tr><tr><td><code>return_url</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Es la url a la que quieres llevar al usuario después de completar el pago. Aplica para pagos por PSE o con link de pago.<br><br><em><mark style="color:blue;"><code>Ejemplo:https://minegocio.com/mi-aplicacion</code></mark></em></td></tr><tr><td><code>expiration</code></td><td><span data-option="VIiuN2CCxiaY">boolean</span></td><td>Define si la transacción debe cancelarse al alcanzar la <strong>limit date</strong>. Por defecto, este valor es <strong>false</strong>.</td></tr><tr><td><code>attachment</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Adjunto que funciona como soporte del cobro.</td></tr><tr><td><code>comments</code></td><td><span data-option="sFwIPm2Dqll0">string</span></td><td>Comentario opcional para tener como referencia al consultar las transacciones en el dashboard.</td></tr></tbody></table>

{% hint style="info" %}
Solo es obligatorio uno de los campos:  merchant\_id\_number, merchant\_phone o merchant\_email.&#x20;
{% endhint %}

### **Información cliente/pagador**

<table><thead><tr><th width="249">Name</th><th width="113">Type<select><option value="tW4OOsURXuNZ" label="string" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><code>payer.phone</code></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td><p>Número de celular del cliente (incluir el código de área del país).  </p><p></p><p><em>Obligatorio en caso del que el channel sea <strong>whatsapp</strong> y el status no sea <strong>created</strong>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 573112223333</code></mark></em></p></td></tr><tr><td><code>payer.email</code></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Correo del cliente al que se enviarán las notificaciones.<br><br><em>Obligatorio en caso del que el channel sea <strong>email</strong> y el status no sea <strong>created</strong>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: cliente@minegocio.com</code></mark></em></td></tr><tr><td><code>payer.user_id_type</code></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Tipo de documento de identificación del cliente.<br><br><mark style="color:green;"><code>CC | CE | NIT | PASAPORTE | DNI | EIN</code></mark></td></tr><tr><td><code>payer.user_id_number</code></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Número del documento de identificación del cliente.<br><br><em><mark style="color:blue;"><code>Ejemplo: 11119999</code></mark></em></td></tr><tr><td><code>payer.first_name</code></td><td><span data-option="tW4OOsURXuNZ">string</span></td><td>Primer nombre del cliente, el cual se usa para la validación del número de documento.<br><br><em><mark style="color:blue;"><code>Ejemplo: Andrés</code></mark></em></td></tr></tbody></table>

{% hint style="warning" %}
Los campos: *`payer.user_id_type`*, *`payer.user_id_number`* y *`payer.first_name`* deben completarse de manera conjunta en la API. Esto significa que si se proporciona uno de estos campos, los otros dos también deben ser proporcionados. Son interdependientes y necesarios para garantizar la integridad de la información del usuario en la plataforma.
{% endhint %}

### Información de afiliados

<table><thead><tr><th width="249">Name</th><th width="113">Type<select><option value="rRB3kMFO5APd" label="string" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:orange;"><code>affiliate.id_type</code></mark></td><td><span data-option="rRB3kMFO5APd">string</span></td><td>Tipo de documento de identificación del afiliado.<br><br><mark style="color:green;"><code>CC | CE | NIT | PASAPORTE | DNI | EIN</code></mark></td></tr><tr><td><mark style="color:orange;"><code>affiliate.id_number</code></mark></td><td><span data-option="rRB3kMFO5APd">string</span></td><td>Número del documento de identificación del afiliado.<br><br><em><mark style="color:blue;"><code>Ejemplo: 11119999</code></mark></em></td></tr></tbody></table>

### **Información de facturación**

<table><thead><tr><th width="249">Name</th><th width="113">Type<select><option value="CRQXJNwgXiB2" label="string" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:purple;"><code>invoice.provider</code></mark></td><td><span data-option="CRQXJNwgXiB2">string</span></td><td><p>Agrega el software contable con el que realizaste la integración.</p><p></p><p><em>Obligatorio para el objeto <strong>invoice</strong>.</em><br><br><mark style="color:green;"><code>alegra | siigo</code></mark></p></td></tr><tr><td><mark style="color:purple;"><code>invoice.type</code></mark></td><td><span data-option="CRQXJNwgXiB2">string</span></td><td><p>Elige el tipo de vinculación que quieres realizar para esta transacción con tu software contable.</p><p></p><p><em>Obligatorio para el objeto <strong>invoice</strong>.</em><br><br><mark style="color:green;"><code>link | balance | create</code></mark></p></td></tr><tr><td><mark style="color:purple;"><code>invoice.id</code></mark></td><td><span data-option="CRQXJNwgXiB2">string</span></td><td>Corresponde al identificador de la factura o el cliente según el tipo de vinculación definido.<br><br><em><mark style="color:blue;"><code>Ejemplo: FV-2-1234 | GR1234 |</code></mark></em><mark style="color:blue;"><code> </code><code>41515fb0-d815-40ac-86c0-4081eb642fa2</code></mark></td></tr><tr><td><mark style="color:purple;"><code>invoice.retentions</code></mark></td><td><span data-option="CRQXJNwgXiB2">string</span></td><td>Solo si la vinculación es <code>create</code>, agregar las retenciones aplicables para la creación de la factura. <strong>Tener en cuenta que el valor de la factura será el valor de la transacción mas las retenciones definidas.</strong><br><br><mark style="color:green;"><code>Formato: enviar las retenciones separadas por comas</code></mark><br><br><em><mark style="color:blue;"><code>Ejemplo: [1,2,3]</code></mark></em></td></tr></tbody></table>

### **Información de recargos**

<table><thead><tr><th width="252.20001220703125">Name</th><th width="113">Type<select><option value="qBeT2Xqfqzst" label="string" color="blue"></option><option value="fqKgpLHMeRsK" label="array" color="blue"></option><option value="DbIS6pyjqlWy" label="numeric" color="blue"></option><option value="EjFL03h7GPMG" label="date" color="blue"></option><option value="9Yt4blEICw5U" label="boolean" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:yellow;"><code>late_fees.condition_type</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Tipo de recargo que se desea aplicar. En el caso de <strong>fixed</strong>, es posible personalizar completamente los periodos y los montos. Con la opción <strong>automated</strong>, los recargos se generan automáticamente a partir de los parámetros: <strong>type</strong>, <strong>value</strong>, <strong>frequency</strong> y <strong>limit</strong>.<br><br><mark style="color:green;"><code>fixed | automated</code></mark></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.type</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td><p>Tipo de incremento del valor. Selecciona <strong>amount</strong> si deseas sumar valores fijos, o <strong>percentage</strong> para aplicar incrementos porcentuales.</p><p></p><p><em>Obligatorio en caso del que el condition_type sea <strong>automated</strong>.</em><br><br><mark style="color:green;"><code>amount | percentage</code></mark></p></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.value</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td><p>Valor fijo o porcentual que se suma al monto. En el caso de porcentajes, deben expresarse en formato decimal (por ejemplo, 0.05 para un 5%).</p><p></p><p><em>Obligatorio en caso del que el condition_type sea <strong>automated</strong>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 1234.5</code></mark></em></p></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.frequency</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td><p>Frecuencia, en días, con la que se aplicará el aumento. El valor máximo permitido es de 30 días.</p><p></p><p><em>Obligatorio en caso del que el condition_type sea <strong>automated</strong>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 3</code></mark></em></p></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.limit</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Límite de veces que se aplicará el aumento. El valor máximo permitido es 30.<br><br><em><mark style="color:blue;"><code>Ejemplo: 5</code></mark></em></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.fixed</code></mark></td><td><span data-option="fqKgpLHMeRsK">array</span></td><td><p>Corresponde a una lista de objetos que contienen los aumentos y sus fechas correspondientes.</p><p></p><p><em>Obligatorio en caso del que el condition_type sea <strong>fixed</strong>.</em></p></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.fixed[].value</code></mark></td><td><span data-option="DbIS6pyjqlWy">numeric</span></td><td>Valor correspondiente al aumento.<br><br><em>Obligatorio en caso del que el condition_type sea <strong>fixed</strong>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 5000</code></mark></em></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.fixed[].date</code></mark></td><td><span data-option="EjFL03h7GPMG">date</span></td><td>Fecha correspondiente al aumento.<br><br><em>Obligatorio en caso del que el condition_type sea <strong>fixed</strong>.</em><br><br><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></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.fixed[].reminder</code></mark></td><td><span data-option="9Yt4blEICw5U">boolean</span></td><td>En caso de que se desee recibir una notificación en el momento en que se aplique el recargo.<br><br><em>Por defecto: <strong>false</strong></em></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.fixed[].reminder_template</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Nombre del mensaje que se le envía para dicho recargo.<br><br><em>Obligatorio en caso del que el reminder sea <strong>true</strong>.</em></td></tr><tr><td><mark style="color:yellow;"><code>late_fees.fixed[].reminder_channel</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Canal por el cual se le va enviar la notificación.<br><br><em>Obligatorio en caso del que el reminder sea <strong>true</strong>.</em><br><br><mark style="color:green;"><code>whatsapp | email</code></mark></td></tr></tbody></table>

### **Información de pagos anticipados**

<table><thead><tr><th width="252.20001220703125">Name</th><th width="113">Type<select><option value="qBeT2Xqfqzst" label="string" color="blue"></option><option value="fqKgpLHMeRsK" label="array" color="blue"></option><option value="DbIS6pyjqlWy" label="numeric" color="blue"></option><option value="EjFL03h7GPMG" label="date" color="blue"></option><option value="9Yt4blEICw5U" label="boolean" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:orange;"><code>advance_payment.condition_type</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Tipo de incentivos que se desea aplicar. En el caso de <strong>fixed</strong>, es posible personalizar completamente los periodos y los montos. Con la opción <strong>automated</strong>, los descuentos se generan automáticamente a partir de los parámetros: <strong>type</strong>, <strong>value</strong>, <strong>frequency</strong> y <strong>limit</strong>.<br><br><mark style="color:green;"><code>fixed | automated</code></mark></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.type</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td><p>Tipo de incentivo del valor. Selecciona <strong>amount</strong> si deseas sumar valores fijos, o <strong>percentage</strong> para aplicar descuentos porcentuales.</p><p></p><p><em>Obligatorio en caso del que el condition_type sea <strong>automated</strong>.</em><br><br><mark style="color:green;"><code>amount | percentage</code></mark></p></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.value</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td><p>Valor fijo o porcentual que se resta al monto. En el caso de porcentajes, deben expresarse en formato decimal (por ejemplo, 0.05 para un 5%).</p><p></p><p><em>Obligatorio en caso del que el condition_type sea <strong>automated</strong>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 1234.5</code></mark></em></p></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.frequency</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td><p>Frecuencia, en días, con la que se aplicará el descuento. El valor máximo permitido es de 30 días.</p><p></p><p><em>Obligatorio en caso del que el condition_type sea <strong>automated</strong>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 3</code></mark></em></p></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.limit</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Límite de veces que se aplicará el descuento. El valor máximo permitido es 30.<br><br><em><mark style="color:blue;"><code>Ejemplo: 5</code></mark></em></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.fixed</code></mark></td><td><span data-option="fqKgpLHMeRsK">array</span></td><td><p>Corresponde a una lista de objetos que contienen los aumentos y sus fechas correspondientes.</p><p></p><p><em>Obligatorio en caso del que el condition_type sea <strong>fixed</strong>.</em></p></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.fixed[].value</code></mark></td><td><span data-option="DbIS6pyjqlWy">numeric</span></td><td>Valor correspondiente al descuento.<br><br><em>Obligatorio en caso del que el condition_type sea <strong>fixed</strong>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 5000</code></mark></em></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.fixed[].date</code></mark></td><td><span data-option="EjFL03h7GPMG">date</span></td><td>Fecha correspondiente al descuento.<br><br><em>Obligatorio en caso del que el condition_type sea <strong>fixed</strong>.</em><br><br><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></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.fixed[].reminder</code></mark></td><td><span data-option="9Yt4blEICw5U">boolean</span></td><td>En caso de que se desee recibir una notificación en el momento en que se aplique el incentivo.<br><br><em>Por defecto: <strong>false</strong></em></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.fixed[].reminder_template</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Nombre del mensaje que se le envía para dicho incentivo.<br><br><em>Obligatorio en caso del que el reminder sea <strong>true</strong>.</em></td></tr><tr><td><mark style="color:orange;"><code>advance_payment.fixed[].reminder_channel</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Canal por el cual se le va enviar la notificación.<br><br><em>Obligatorio en caso del que el reminder sea <strong>true</strong>.</em><br><br><mark style="color:green;"><code>whatsapp | email</code></mark></td></tr></tbody></table>

### **Información de items**

<table><thead><tr><th width="252.20001220703125">Name</th><th width="113">Type<select><option value="qBeT2Xqfqzst" label="string" color="blue"></option><option value="fqKgpLHMeRsK" label="array" color="blue"></option><option value="DbIS6pyjqlWy" label="numeric" color="blue"></option><option value="EjFL03h7GPMG" label="date" color="blue"></option><option value="9Yt4blEICw5U" label="boolean" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:orange;"><code>items.code</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Código que identifica a el artículo.<br><br><em><mark style="color:blue;"><code>Ejemplo: 1050</code></mark></em></td></tr><tr><td><mark style="color:orange;"><code>items.description</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Descripción del artículo.<br><br><em><mark style="color:blue;"><code>Ejemplo: Correa 20cm</code></mark></em>   </td></tr><tr><td><mark style="color:orange;"><code>items.quantity</code></mark></td><td><span data-option="DbIS6pyjqlWy">numeric</span></td><td>Cantidad de items agregados.<br><br><em><mark style="color:blue;"><code>Ejemplo: 1234.5</code></mark></em></td></tr><tr><td><mark style="color:orange;"><code>items.unit_of_measure</code></mark></td><td><span data-option="qBeT2Xqfqzst">string</span></td><td>Unidad de medida de los items.<br><br><em><mark style="color:blue;"><code>Ejemplo: und</code></mark></em> </td></tr><tr><td><mark style="color:orange;"><code>items.unit_price</code></mark></td><td><span data-option="DbIS6pyjqlWy">numeric</span></td><td>Precio por unidad del artículo.<br><br><em><mark style="color:blue;"><code>Ejemplo: 5000</code></mark></em></td></tr><tr><td><mark style="color:orange;"><code>items.category</code></mark></td><td><span data-option="fqKgpLHMeRsK">array</span></td><td><p>Categoría a la cual corresponde el artículo.</p><p></p><p><em><mark style="color:blue;"><code>Ejemplo: Ropa</code></mark></em></p></td></tr></tbody></table>

## **Respuesta**

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

```json
{
    "external_reference": "f6a886",
    "channel": "WHATSAPP",
    "link": "https://pago.trazo.co/prueba/t/a1a2a3",
    "process_id": "a1a2a3a4-a123-b456-c7890-b1b2b3b4b5b6",
    "created_at": "2024-08-26T21:07:23+00:00"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": [
        "\"amount\" must be a number"
    ]
}
```

{% 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/transaction' \
--header 'x-auth-token: {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "status": "PENDING",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "reference_seven": "Referencia 7",
    "reference_eight": "Referencia 8",
    "return_url": "https://www.trazo.com",
    "channel": "WHATSAPP",
    "user_notification": "true",
    "merchant_phone": "573112223333",
    "reminder_date": "02/10/2025",
    "expected_date": "10/20/2025",
    "payer": {
        "phone": "573112223333"
    },
    "affiliate": {
        "id_number": "1234567890"
    },
    "invoice": {
        "provider": "siigo",
        "type": "link",
        "id": "FV-12-12345678"
    }
}'
```

{% endtab %}

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

```javascript
const axios = require('axios');
let data = JSON.stringify({
  "status": "PENDING",
  "amount": 100000,
  "currency": "COP",
  "description": "Descripción Transacción",
  "reference_one": "Referencia 1",
  "reference_two": "Referencia 2",
  "reference_three": "Referencia 3",
  "reference_four": "Referencia 4",
  "reference_five": "Referencia 5",
  "reference_six": "Referencia 6",
  "reference_seven": "Referencia 7",
  "reference_eight": "Referencia 8",
  "return_url": "https://www.trazo.com",
  "channel": "WHATSAPP",
  "user_notification": "true",
  "merchant_phone": "573112223333",
  "reminder_date": "02/10/2025",
  "expected_date": "10/20/2025",
  "payer": {
    "phone": "573112223333"
  },
  "affiliate": {
    "id_number": "1234567890"
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: `${base_url}/v1/merchant/transaction`,
  headers: { 
    'x-auth-token': token //Agregar el 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
import json

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

payload = json.dumps({
  "status": "PENDING",
  "amount": 100000,
  "currency": "COP",
  "description": "Descripción Transacción",
  "reference_one": "Referencia 1",
  "reference_two": "Referencia 2",
  "reference_three": "Referencia 3",
  "reference_four": "Referencia 4",
  "reference_five": "Referencia 5",
  "reference_six": "Referencia 6",
  "reference_seven": "Referencia 7",
  "reference_eight": "Referencia 8",
  "return_url": "https://www.trazo.com",
  "channel": "WHATSAPP",
  "user_notification": "true",
  "merchant_phone": "573112223333",
  "reminder_date": "02/10/2025",
  "expected_date": "10/20/2025",
  "payer": {
    "phone": "573112223333"
  },
  "affiliate": {
    "id_number": "1234567890"
  }
})
headers = {
  'x-auth-token': token, #Agregar el token
  'Content-Type': 'application/json'
}

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

print(response.text)

```

{% endtab %}
{% endtabs %}

***

## Caso de uso&#x20;

<details>

<summary>Cobro inmediato con notificación en WhatsApp (con datos de usuario)</summary>

```bash
curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "created",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "whatsapp",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "phone": "573112223333"
    }
    
}'
```

</details>

<details>

<summary>Cobro sin vencimiento con notificación en correo (con datos de usuario)</summary>

```bash
curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "unlimit",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "email",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "email": "correo@qentaz.com"
    }
    
}'
```

</details>

<details>

<summary>Cobro programado con notificación en correo (con datos de usuario)</summary>

```bash
curl --location --request POST '{base_url}/v1/merchant/transaction' \
--header 'x-auth-token: {token}' \
--header 'Content-Type: application/json' \

--data-raw '{
    "status": "unlimit",
    "amount": 100000,
    "currency": "COP",
    "description": "Descripción Transacción",
    "reference_one": "Referencia 1",
    "reference_two": "Referencia 2",
    "reference_three": "Referencia 3",
    "reference_four": "Referencia 4",
    "reference_five": "Referencia 5",
    "reference_six": "Referencia 6",
    "channel": "email",
    "merchant_phone": "573112223333",
    "return_url": "https://www.qentaz.com/",
    "reminder_date": "02/10/2023",
   "expected_amount": 100000,
   "expected_date": "10/20/2023",
    "payer": {
        "phone": "573112223333",
        "email": "correo@qentaz.com",
        "first_name": "Andrés",
        "user_id_type": "CC",
        "user_id_number": "123456789"
    }
    
}'
```

</details>

***


---

# 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/cobros/generar-cobro.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.