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

# Generar Cobro

Crea una nueva solicitud de cobro para iniciar un flujo de pago. A través de este endpoint, puedes parametrizar de forma flexible todas las reglas de cobro, configuraciones operativas y demás datos asociados a la transacción.

## Endpoint

<mark style="color:green;">`POST`</mark> `{{base_url}}/transaction`

## **Headers**

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

## **Body**&#x20;

### **Información general**

Campos base para la identificación y control del cobro en la plataforma.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="217.71484375">Campo</th><th width="120.27734375">Tipo</th><th width="120.27734375">Obligatorio</th><th width="289.73046875">Descripción</th></tr></thead><tbody><tr><td><code>status</code></td><td>String</td><td>Sí</td><td>Estado inicial asignado al cobro. Por defecto: PENDING.<br><br><mark style="color:green;"><code>CREATED | PENDING | SCHEDULED</code></mark></td></tr><tr><td><code>currency</code></td><td>String</td><td>Sí</td><td><p>Código de la divisa del cobro bajo el estándar ISO 4217.<br></p><p><mark style="color:green;"><code>COP | USD</code></mark></p></td></tr><tr><td><code>amount</code></td><td>Numeric</td><td>Sí</td><td><p>Importe final definitivo a recibir por el producto o servicio.</p><p></p><p>ℹ️ <em>El monto debe ser estrictamente mayor a 0</em> y emplear el punto . como separador decimal.</p><p></p><p><em><mark style="color:blue;"><code>Ejemplo: 54000.85</code></mark></em></p></td></tr><tr><td><code>description</code></td><td>String</td><td>Sí</td><td><p>Detalle principal o motivo del cobro. Se refleja directamente en los comprobantes de pago emitidos al cliente.</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>String</td><td>No</td><td><p>Campos independientes de uso libre para mapear información adicional del cobro (ej. número de orden, categoría).</p><p></p><p>ℹ️ <em>La <code>reference_one</code> es visible en algunas partes de la experiencia del usuario.</em></p><p><br><em><mark style="color:blue;"><code>Ejemplo: FAC123</code></mark></em></p></td></tr><tr><td><code>expected_amount</code></td><td>Numeric</td><td>No</td><td><p>Valor esperado del cobro. Campo 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 valor de <code>amount</code>.</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>String</td><td>No</td><td>Fecha estimada de finalización de la transacción. Campo 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>merchant_id_number</code></td><td>String</td><td>Condicional</td><td><p>Número de documento del usuario que genera el cobro.</p><p></p><p><em>⚠️ Requerido si se omiten <code>merchant_phone</code> y <code>merchant_email</code>.</em><br></p><p><em><mark style="color:blue;"><code>Ejemplo: 100110000</code></mark></em></p></td></tr><tr><td><code>merchant_phone</code></td><td>String</td><td>Condicional</td><td><p>Número de celular del usuario que genera el cobro (incluir el código de área del país).</p><p></p><p><em>⚠️ Requerido si se omiten <code>merchant_id_number</code> y <code>merchant_email</code>.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 573112229999</code></mark></em></p></td></tr><tr><td><code>merchant_email</code></td><td>String</td><td>Condicional</td><td><p>Correo del usuario que genera el cobro.<br></p><p><em>⚠️ Requerido si se omiten <code>merchant_id_number</code> y <code>merchant_phone</code>.</em></p><p><br><em><mark style="color:blue;"><code>Ejemplo: alguien@ejemplo.com</code></mark></em></p></td></tr><tr><td><code>attachment</code></td><td>String</td><td>No</td><td>Agrega un adjunto que funciona como soporte del cobro.</td></tr><tr><td><code>comments</code></td><td>String</td><td>No</td><td>Comentarios o notas de uso interno para tener como referencia al consultar las transacciones.</td></tr></tbody></table>

### Comunicación

Configura los canales y las reglas de mensajería para mantener a tu cliente informado sobre el estado de su cobro.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="217.9140625">Campo</th><th width="119.9375">Tipo</th><th width="119.873046875">Obligatorio</th><th width="290.48046875">Descripción</th></tr></thead><tbody><tr><td><code>channel</code></td><td>String</td><td>No</td><td><p>Canal por el que se notificará al cliente, bien sea la generación del cobro y/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 | EMAIL | LINK</code></mark></p></td></tr><tr><td><code>user_notification</code></td><td>Boolean</td><td>No</td><td><p>Define si el sistema debe enviar de forma automática la notificación del cobro hacia el usuario final.</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>return_url</code></td><td>String</td><td>No</td><td><p>Enlace al que será redireccionado el usuario de manera automática una vez complete exitosamente el proceso de pago.<br></p><p><em>ℹ️ No aplica para pagos en chat.</em></p><p><br><em><mark style="color:blue;"><code>Ejemplo:https://minegocio.com/mi-aplicacion</code></mark></em></p></td></tr><tr><td><code>custom_webhook</code></td><td>String</td><td>No</td><td><p>Si necesitas que los eventos de esta transacción en específico (como el éxito o fallo del pago) se notifiquen a una URL distinta a la que configuraste globalmente, envía aquí tu enlace personalizado.</p><p><br><em><mark style="color:blue;"><code>Ejemplo: https://miwebhook.com/status</code></mark></em></p></td></tr></tbody></table>

### **Información cliente/pagador** *<mark style="color:$info;">`[payer]`</mark>*

Guarda los datos de identificación y contacto del cliente que va a pagar para minimizar pasos en el proceso de pago y confirmación.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="217.5078125">Campo</th><th width="120.3203125">Tipo</th><th width="120.04296875">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td><code>payer.phone</code></td><td>String</td><td>Condicional</td><td><p>Número de teléfono celular del cliente pagador (debe incluir el código de área internacional).</p><p></p><p><em>⚠️ Es obligatorio si el campo <code>channel</code> está configurado como WHATSAPP y el <code>status</code> del cobro es diferente a CREATED.</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>String</td><td>Condicional</td><td>Correo del cliente al que se enviarán las notificaciones.<br><br><em>⚠️ Es obligatorio si el campo <code>channel</code> está configurado como EMAIL y el <code>status</code> del cobro es diferente a CREATED.</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>String</td><td>Condicional</td><td><p>Tipo de documento de identificación del cliente.</p><p></p><p><em>⚠️ Sujeto a la regla de interdependencia.</em><br><br><mark style="color:green;"><code>CC | CE | NIT | PASAPORTE | DNI | EIN</code></mark></p></td></tr><tr><td><code>payer.user_id_number</code></td><td>String</td><td>Condicional</td><td><p>Número del documento de identificación del cliente.</p><p></p><p><em>⚠️ Sujeto a la regla de interdependencia.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 11119999</code></mark></em></p></td></tr><tr><td><code>payer.first_name</code></td><td>String</td><td>Condicional</td><td><p>Primer nombre del cliente, el cual se usa para la validación del número de documento.</p><p></p><p><em>⚠️ Sujeto a la regla de interdependencia.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: Andrés</code></mark></em></p></td></tr></tbody></table>

{% hint style="warning" %}
Los campos: *`payer.user_id_type`*, *`payer.user_id_number`* y *`payer.first_name`* operan bajo una lógica de **obligatoriedad conjunta**. Si decides enviar cualquiera de estos tres campos en el JSON, **los otros dos se vuelven obligatorios de inmediato** para asegurar la consistencia y el correcto procesamiento del fraude/recaudo en Trazo.
{% endhint %}

### Vencimiento y Ajustes Dinámicos

Configura la vigencia de tus cobros y parametriza reglas financieras automáticas para aplicar recargos por mora o incentivos por pronto pago. Para habilitar estas reglas de ajustes, es mandatorio configurar primero los parámetros de vigencia del cobro:

<table><thead><tr><th width="218.48046875">Campo</th><th width="120.453125">Tipo</th><th width="119.66796875">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td><code>limit_date</code></td><td>Date</td><td>Condicional</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 descuentos, este campo se vuelve estrictamente 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>expiration</code></td><td>Boolean</td><td>No</td><td>Determina el comportamiento al vencerse el cobro. Si se configura en <code>true</code>, el cobro se cancelará al alcanzar la fecha límite. Por defecto es false.<br><br><em>ℹ️ Por defecto es false.</em><br><br><mark style="color:green;"><code>true | false</code></mark></td></tr></tbody></table>

Para aplicar recargos o descuentos, la API recibe dos objetos independientes en la raíz de la petición. Ambos comparten exactamente la misma estructura interna de parámetros, diferenciándose únicamente en su impacto sobre el monto final:

* **Recargos** *<mark style="color:$info;">`[late_fee]`</mark>***:** Incrementos aplicados en fechas posteriores a la fecha límite que se suman al valor base.
* **Descuentos** *<mark style="color:$info;">`[advance_payment]`</mark>***:** Incentivos aplicados en fechas anteriores a la fecha límite que se restan del valor base.

Los siguientes campos corresponden a la estructura interna de las reglas de negocio. En tu payload, debes reemplazar la palabra AJUSTE por `late_fees` o por `advance_payment` según corresponda (ten en cuenta que ninguno de estos parámetros va suelto en la raíz del JSON):

{% tabs %}
{% tab title="Ajustes Fijos" icon="square-plus" %}

<table><thead><tr><th width="252.20001220703125">Campo</th><th width="113">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td><code>AJUSTE.condition_type</code></td><td>String</td><td><p>Indica cómo vas a programar los recargos o descuentos. En esta pestaña aplican los <strong>ajustes fijos</strong>, es decir, que defines las fechas exactas y los montos a ajustar.<br></p><p><em>ℹ️ El valor para debe ser estrictamente <code>fixed</code>.</em></p></td></tr><tr><td><code>AJUSTE.fixed[].value</code></td><td>Number</td><td><p>Es el monto exacto de dinero que se va a sumar (como recargo) o a restar (como descuento) en esta fecha específica.</p><p></p><p><em>Si se envía un valor menor a 1 (Ej: 0.05), se tomará como porcentual.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 5000</code></mark></em></p></td></tr><tr><td><code>AJUSTE.fixed[].date</code></td><td>Date</td><td>Fecha exacta hasta la que aplica el recargo o descuento.<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>AJUSTE.fixed[].reminder</code></td><td>Boolean</td><td>Indica si quieres que el sistema le envíe una notificación automática a tu cliente en el momento exacto en que se aplique este recargo o descuento.<br><br><em>ℹ️ Por defecto es false.</em></td></tr></tbody></table>

{% hint style="info" %}
Como el campo `fixed` es una lista, no estás limitado a poner un solo recargo o descuento. Puedes agregar todos los que quieras dentro del mismo bloque. *Por ejemplo:* Puedes programar un primer recargo de $5,000 el 5 de febrero, un segundo recargo de $10,000 el 12 de febrero y un último recargo de $15,000 el 20 de febrero. El sistema los irá aplicando todos en orden conforme pasen las fechas.
{% endhint %}
{% endtab %}

{% tab title="Ajustes Automáticos" icon="clone-plus" %}

<table><thead><tr><th width="252.20001220703125">Campo</th><th width="113">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td><code>AJUSTE.condition_type</code></td><td>String</td><td>Indica cómo vas a programar los recargos o descuentos. En esta pestaña aplican los <strong>ajustes automáticos</strong>, es decir, que configuras las reglas para que el sistema calcule y repita los montos por su cuenta cada cierto tiempo.<br><br><em>ℹ️ El valor debe ser estrictamente <code>automated</code>.</em></td></tr><tr><td><code>AJUSTE.type</code></td><td>String</td><td>Elige cómo se va a calcular el recargo o el descuento. Escribe <em>AMOUNT</em> si quieres que sea un monto de dinero fijo (por ejemplo: $5,000) o <em>PERCENTAGE</em> si prefieres aplicar un porcentaje (por ejemplo: el 5%).<br><br><mark style="color:green;"><code>AMOUNT | PERCENTAGE</code></mark></td></tr><tr><td><code>AJUSTE.value</code></td><td>Number</td><td>Valor fijo o porcentual que se va a aplicar. En el caso de porcentajes, deben expresarse en formato decimal (por ejemplo, 0.05 para un 5%).<br><br><em><mark style="color:blue;"><code>Ejemplo: 1234.5</code></mark></em></td></tr><tr><td><code>AJUSTE.frequency</code></td><td>Integer</td><td>Indica cada cuántos días quieres que el sistema repita y aplique este ajuste. El número máximo permitido es 30 días (por ejemplo: si pones 7, el recargo o descuento se aplicará cada semana).<br><br><em><mark style="color:blue;"><code>Ejemplo: 3</code></mark></em></td></tr><tr><td><code>AJUSTE.limit</code></td><td>Integer</td><td>Es la cantidad máxima de veces que se puede llegar a repetir y acumular este recargo o descuento. El límite máximo permitido por el sistema es de <code>30</code> veces.<br><br><em><mark style="color:blue;"><code>Ejemplo: 5</code></mark></em></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### **Facturación** *<mark style="color:$info;">`[invoice]`</mark>*

Configura la sincronización automatizada de tus transacciones con tu sistema contable preferido.&#x20;

<table><thead><tr><th width="217.94964599609375">Campo</th><th width="119.9921875">Tipo</th><th width="119.9869384765625">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td><code>invoice.provider</code></td><td>String</td><td>Condicional</td><td><p>Agrega el software contable con el que realizaste la integración.</p><p></p><p><em>⚠️ Obligatorio si envías el objeto invoice.</em><br><br><mark style="color:green;"><code>ALEGRA | SIIGO | SAPB1 | SAP4HANA | ODOO</code></mark></p></td></tr><tr><td><code>invoice.type</code></td><td>String</td><td>Condicional</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 si envías el objeto invoice.</em><br><br><mark style="color:green;"><code>LINK | BALANCE | CREATE</code></mark></p></td></tr><tr><td><code>invoice.key</code></td><td>String</td><td>No</td><td><p>Indica qué tipo de dato estás enviando en el campo invoice.id. </p><p></p><p>Valores permitidos:</p><ul><li><em>id</em>: Si el valor es el identificador único interno de tu software.</li><li><em>number</em>: Si estás usando el número consecutivo de la factura (ej: FV-123).</li></ul><p></p><p><em>ℹ️ Por defecto toma el valor de id si no lo envías.</em></p></td></tr><tr><td><code>invoice.id</code></td><td>String</td><td>No</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></tbody></table>

### **Información de items** *<mark style="color:$info;">`[items]`</mark>*

Desglosa los productos o servicios incluidos en este cobro.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="217.59930419921875">Campo</th><th width="119.7838134765625">Tipo</th><th width="120.2777099609375">Obligatoria</th><th>Descripción</th></tr></thead><tbody><tr><td><code>items.code</code></td><td>String</td><td>Condicional</td><td><p>Código único que identifica al artículo dentro de tu inventario (SKU o ID interno). </p><p></p><p><em>⚠️ Obligatorio si se incluye el arreglo items.</em> <br><br><em><mark style="color:blue;"><code>Ejemplo: 1050</code></mark></em></p></td></tr><tr><td><code>items.description</code></td><td>String</td><td>Condicional</td><td><p>Nombre comercial, detalle o descripción del producto o servicio que se está cobrando.<br></p><p><em>⚠️ Obligatorio si se incluye el arreglo items.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: Correa 20cm</code></mark></em></p></td></tr><tr><td><code>items.unit_of_measure</code></td><td>String</td><td>No</td><td>La unidad de medida que define al artículo. Puedes usar valores estándar del mercado (por ejemplo: und para unidades, kg para kilogramos, hrs para horas).<br><br><em><mark style="color:blue;"><code>Ejemplo: und</code></mark></em> </td></tr><tr><td><code>items.quantity</code></td><td>Number</td><td>Condicional</td><td><p>Cantidad de unidades añadidas de este artículo. <em>Soporta valores decimales en caso de que cobres por peso, medidas o fracciones de tiempo.</em></p><p></p><p><em>⚠️ Obligatorio si se incluye el arreglo items.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 12</code></mark></em></p></td></tr><tr><td><code>items.unit_price</code></td><td>Number</td><td>Condicional</td><td><p>Precio por unidad del artículo.</p><p></p><p><em>⚠️ Obligatorio si se incluye el arreglo items.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 5000</code></mark></em></p></td></tr><tr><td><code>items.category</code></td><td>String</td><td>No</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><tr><td><code>items.tax_name</code></td><td>String</td><td>No</td><td>Nombre técnico o etiqueta del impuesto que aplica a este artículo en específico.<br><br><em><mark style="color:blue;"><code>Ejemplo: IVA</code></mark></em></td></tr><tr><td><code>items.tax_amount</code></td><td>Number</td><td>No</td><td>El valor o monto en dinero del impuesto correspondiente a este artículo.<br><br><em><mark style="color:blue;"><code>Ejemplo: 100</code></mark></em></td></tr></tbody></table>

### **Ubicación** *<mark style="color:$info;">`[location]`</mark>*

Guarda la dirección física o las coordenadas geográficas del lugar donde se realiza la transacción o se entrega el servicio.

<table><thead><tr><th width="217.95050048828125">Campo</th><th width="120.2620849609375">Tipo</th><th width="119.998291015625">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td><code>location.address</code></td><td>String</td><td>No</td><td><p>Dirección de calle, avenida o nomenclatura física del lugar.</p><p></p><p><em><mark style="color:blue;"><code>Ejemplo: Calle 45 #12-34, Bogotá</code></mark></em></p></td></tr><tr><td><code>location.latitude</code></td><td>String</td><td>No</td><td><p>Coordenada de latitud geográfica del punto de venta o entrega.<br></p><p><em><mark style="color:blue;"><code>Ejemplo: 4.6097</code></mark></em></p></td></tr><tr><td><code>location.longitude</code></td><td>String</td><td>No</td><td><p>Coordenada de longitud geográfica del punto de venta o entrega.</p><p><br><em><mark style="color:blue;"><code>Ejemplo: -74.6097</code></mark></em></p></td></tr></tbody></table>

### **Recordatorios** *<mark style="color:$info;">`[reminders]`</mark>*

Programa alertas automáticas para recordarle a tu cliente que tiene un pago pendiente antes de que llegue la fecha de vencimiento.&#x20;

<table><thead><tr><th width="217.96875">Campo</th><th width="119.55078125">Tipo</th><th width="120.49609375">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td>reminders[].date</td><td>Date</td><td>Condicional</td><td><p>La fecha exacta en la que se debe disparar el recordatorio.</p><p><br><em>⚠️ Obligatorio si se incluye el arreglo reminders.</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>reminders[].channel</td><td>String</td><td>Condicional</td><td>El canal a través del cual se enviará el mensaje.<br><br><mark style="color:green;"><code>WHATSAPP | EMAIL | LINK</code></mark></td></tr><tr><td>reminders[].template</td><td>String</td><td>Condicional</td><td><p>El nombre o identificador de la plantilla de mensaje preconfigurada.</p><p><br><em>⚠️ Obligatorio si se incluye el arreglo reminders.</em></p><p><br><em><mark style="color:blue;"><code>Ejemplo: default</code></mark></em></p></td></tr></tbody></table>

{% hint style="info" %}
Como el campo `reminders` es una lista, no estás limitado a poner un solo recordatorio. Puedes agregar todos los que quieras dentro del mismo bloque. *Por ejemplo:* Puedes programar un primer recordatorio el 5 de febrero, un segundo el 12 de febrero y un último el 20 de febrero.
{% endhint %}

### **Vendedor** *<mark style="color:$info;">`[seller]`</mark>*

Asocia la transacción a un asesor comercial o ejecutivo específico. Es una herramienta ideal para segmentar reportes internos, auditar ventas o calcular comisiones en tu plataforma.

<table><thead><tr><th width="218.40191650390625">Campo</th><th width="120.0799560546875">Tipo</th><th width="119.6727294921875">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td>seller.id_number</td><td>String</td><td>Condicional</td><td><p>Número de documento de identidad oficial del vendedor.</p><p><br><em>⚠️ Obligatorio si se incluye el objeto seller.</em></p><p><br><em><mark style="color:blue;"><code>Ejemplo: 12345678</code></mark></em></p></td></tr><tr><td>seller.id_type</td><td>String</td><td>Condicional</td><td>Tipo de documento de identidad del vendedor.<br><br><em>⚠️ Obligatorio si se incluye el objeto seller.</em><br><br><mark style="color:green;"><code>CC | CE | NIT | PASAPORTE | DNI | EIN</code></mark></td></tr></tbody></table>

### **Tarifas para Cuentas Administradas**

Permite configurar de forma dinámica las comisiones fijas y variables cobradas a una cuenta administrada para este cobro en específico, es decir, que se sobrescriben los valores definidos originalmente al vincular la cuenta.

{% hint style="info" %}
Estos parámetros son de uso exclusivo para plataformas que operan bajo el modelo de cuentas administradas.
{% endhint %}

<table><thead><tr><th width="218.1241455078125">Campo</th><th width="119.732666015625">Tipo</th><th width="119.83935546875">Obligatorio</th><th>Descripción</th></tr></thead><tbody><tr><td>custom_saas_fixed</td><td>Number</td><td>No</td><td><p>Valor de la comisión fija del administrado aplicable a esta transacción.</p><p> </p><p>ℹ️ <em>Si no se envía, Trazo aplicará automáticamente la tarifa fija por defecto del comercio.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 1000</code></mark></em></p></td></tr><tr><td>custom_saas_variable</td><td>Number</td><td>No</td><td><p>Valor de la comisión porcentual del administrador aplicable a esta transacción. Debes expresarlo en formato decimal. <br></p><p>ℹ️ <em>Si no se envía, se aplicará la tasa variable por defecto.</em><br><br><em><mark style="color:blue;"><code>Ejemplo: 0.02</code></mark></em></p></td></tr></tbody></table>

***

## **Response**

{% tabs %}
{% tab title="200" icon="octagon-check" %}

```json
{
    "external_reference": "A1A2A3A4",
    "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" icon="octagon-xmark" %}

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

{% endtab %}

{% tab title="401" icon="hexagon-exclamation" %}

```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 -X POST "{{base_url}}/transaction" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: YOUR_SECRET_TOKEN" \
  -d '{
  "amount": 150000,
  "expected_amount": 150000,
  "currency": "COP",
  "description": "Pago completo del mes",
  "status": "PENDING",
  "channel": "WHATSAPP",
  "merchant_phone": "573001234567",
  "merchant_email": "comercio@empresa.com",
  "merchant_id_number": "900123456",
  "user_notification": true,
  "expected_date": "2026-12-01",
  "limit_date": "2026-12-05",
  "reference_one": "Factura 101",
  "reference_two": "Cliente Preferencial",
  "return_url": "https://comercio.com/exito",
  "payer": {
    "first_name": "Juan Pérez",
    "user_id_type": "CC",
    "user_id_number": "1098765432",
    "phone": "573111222333",
    "email": "juan@ejemplo.com"
  },
  "seller": {
    "id_type": "CC",
    "id_number": "1111111111"
  },
  "invoice": {
    "provider": "siigo",
    "type": "create",
    "key": "id",
    "id": "FAC-999"
  },
  "late_fees": {
    "condition_type": "fixed",
    "fixed": [
      {
        "value": 5000,
        "date": "2026-12-06",
        "reminder": true,
        "reminder_template": "tu_pago_vencido"
      }
    ]
  },
  "advance_payment": {
    "condition_type": "automated",
    "type": "amount",
    "value": 150000,
    "frequency": 30,
    "limit": 3
  },
  "reminders": [
    {
      "date": "2026-12-04",
      "channel": "whatsapp",
      "template": "recordatorio_pago"
    }
  ],
  "attachment": "https://midominio.com/adjunto.pdf",
  "comments": "Creación completa de transacción",
  "custom_webhook": "https://api.comercio.com/webhooks/trazo",
  "items": [
    {
      "code": "SKU-01",
      "description": "Suscripción Premium",
      "quantity": 2,
      "unit_of_measure": "UN",
      "unit_price": 75000,
      "category": "Servicios"
    }
  ],
  "location": {
    "address": "Calle 123 # 45-67",
    "latitude": "4.6097100",
    "longitude": "-74.0817500"
  },
  "custom_saas_fixed": 1500,
  "custom_saas_variable": 0.02
}'
```

{% endtab %}

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

```javascript
const url = '{{base_url}}/transaction';
const token = 'YOUR_SECRET_TOKEN';

const payload = {
  amount: 150000,
  expected_amount: 150000,
  currency: 'COP',
  description: 'Pago completo del mes',
  status: 'PENDING',
  channel: 'WHATSAPP',
  merchant_phone: '573001234567',
  merchant_email: 'comercio@empresa.com',
  merchant_id_number: '900123456',
  user_notification: true,
  expected_date: '2026-12-01',
  limit_date: '2026-12-05',
  reference_one: 'Factura 101',
  reference_two: 'Cliente Preferencial',
  return_url: 'https://comercio.com/exito',
  payer: {
    first_name: 'Juan Pérez',
    user_id_type: 'CC',
    user_id_number: '1098765432',
    phone: '573111222333',
    email: 'juan@ejemplo.com'
  },
  seller: {
    id_type: 'CC',
    id_number: '1111111111'
  },
  invoice: {
    provider: 'siigo',
    type: 'create',
    key: 'id', // <-- ¡Coma corregida aquí!
    id: 'FAC-999'
  },
  late_fees: {
    condition_type: 'fixed',
    fixed: [
      {
        value: 5000,
        date: '2026-12-06',
        reminder: true,
        reminder_template: 'tu_pago_vencido'
      }
    ]
  },
  advance_payment: {
    condition_type: 'automated',
    type: 'amount',
    value: 150000,
    frequency: 30,
    limit: 3
  },
  reminders: [
    {
      date: '2026-12-04',
      channel: 'whatsapp',
      template: 'recordatorio_pago'
    }
  ],
  attachment: 'https://midominio.com/adjunto.pdf',
  comments: 'Creación completa de transacción',
  custom_webhook: 'https://api.comercio.com/webhooks/trazo',
  items: [
    {
      code: 'SKU-01',
      description: 'Suscripción Premium',
      quantity: 2,
      unit_of_measure: 'UN',
      unit_price: 75000,
      category: 'Servicios'
    }
  ],
  location: {
    address: 'Calle 123 # 45-67',
    latitude: '4.6097100',
    longitude: '-74.0817500'
  },
  custom_saas_fixed: 1500,
  custom_saas_variable: 0.02
};

async function createTransaction() {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-auth-token': token
      },
      body: JSON.stringify(payload)
    });

    const data = await response.json();
    console.log('Respuesta:', data);
  } catch (error) {
    console.error('Error:', error);
  }
}

createTransaction();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

# Reemplaza {{base_url}} por la URL de tu entorno (ej: https://api.qentaz.com/v1/merchant)
url = "{{base_url}}/transaction"

headers = {
    "Content-Type": "application/json",
    "x-auth-token": "YOUR_SECRET_TOKEN"
}

payload = {
    "amount": 150000,
    "expected_amount": 150000,
    "currency": "COP",
    "description": "Pago completo del mes",
    "status": "PENDING",
    "channel": "WHATSAPP",
    "merchant_phone": "573001234567",
    "merchant_email": "comercio@empresa.com",
    "merchant_id_number": "900123456",
    "user_notification": True,
    "expected_date": "2026-12-01",
    "limit_date": "2026-12-05",
    "reference_one": "Factura 101",
    "reference_two": "Cliente Preferencial",
    "return_url": "https://comercio.com/exito",
    "payer": {
        "first_name": "Juan Pérez",
        "user_id_type": "CC",
        "user_id_number": "1098765432",
        "phone": "573111222333",
        "email": "juan@ejemplo.com"
    },
    "seller": {
        "id_type": "CC",
        "id_number": "1111111111"
    },
    "invoice": {
        "provider": "siigo",
        "type": "create",
        "key": "id",
        "id": "FAC-999"
    },
    "late_fees": {
        "condition_type": "fixed",
        "fixed": [
            {
                "value": 5000,
                "date": "2026-12-06",
                "reminder": True,
                "reminder_template": "tu_pago_vencido"
            }
        ]
    },
    "advance_payment": {
        "condition_type": "automated",
        "type": "amount",
        "value": 150000,
        "frequency": 30,
        "limit": 3
    },
    "reminders": [
        {
            "date": "2026-12-04",
            "channel": "whatsapp",
            "template": "recordatorio_pago"
        }
    ],
    "attachment": "https://midominio.com/adjunto.pdf",
    "comments": "Creación completa de transacción",
    "custom_webhook": "https://api.comercio.com/webhooks/trazo",
    "items": [
        {
            "code": "SKU-01",
            "description": "Suscripción Premium",
            "quantity": 2,
            "unit_of_measure": "UN",
            "unit_price": 75000,
            "category": "Servicios"
        }
    ],
    "location": {
        "address": "Calle 123 # 45-67",
        "latitude": "4.6097100",
        "longitude": "-74.0817500"
    },
    "custom_saas_fixed": 1500,
    "custom_saas_variable": 0.02
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    print("Transacción creada con éxito.")
    print("Respuesta del servidor:", response.json())
except requests.exceptions.RequestException as e:
    print("Error al realizar la petición:", e)
```

{% endtab %}
{% endtabs %}