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

POST {{base_url}}/transaction

Headers

Name

Value

Content-Type*

application/json

x-auth-token*

{token}

child-id

{business_id}

El child-id es opcional y se usa para las cuentas administradas para conocer más puedes ingresa a este enlace.

Body

Información general

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

Campo

Tipo

Obligatorio

Descripción

status

String

Sí

Estado inicial asignado al cobro. Por defecto: PENDING. CREATED | PENDING | SCHEDULED

currency

String

Sí

Código de la divisa del cobro bajo el estándar ISO 4217.

COP | USD

amount

Numeric

Sí

Importe final definitivo a recibir por el producto o servicio.

ℹ️ El monto debe ser estrictamente mayor a 0 y emplear el punto . como separador decimal.

Ejemplo: 54000.85

description

String

Sí

Detalle principal o motivo del cobro. Se refleja directamente en los comprobantes de pago emitidos al cliente.

ℹ️ La descripción debe contener mínimo 5 caracteres. Ejemplo: Servicio de entrega

reference_one reference_two reference_three reference_four reference_five reference_six reference_seven reference_eight

String

Campos independientes de uso libre para mapear información adicional del cobro (ej. número de orden, categoría).

ℹ️ La reference_one es visible en algunas partes de la experiencia del usuario.

Ejemplo: FAC123

expected_amount

Numeric

Valor esperado del cobro. Campo informativo y no afecta en absoluto el proceso de cobro.

ℹ️ En caso de no suministrar ningún valor se asignara por defecto el valor de amount. Ejemplo: 10000

expected_date

String

Fecha estimada de finalización de la transacción. Campo informativo y no afecta en absoluto el proceso de cobro. Formato: AAAA-MM-DD Ejemplo: 2025-01-30

merchant_id_number

String

Condicional

Número de documento del usuario que genera el cobro.

⚠️ Requerido si se omiten merchant_phone y merchant_email.

Ejemplo: 100110000

merchant_phone

String

Condicional

Número de celular del usuario que genera el cobro (incluir el código de área del país).

⚠️ Requerido si se omiten merchant_id_number y merchant_email. Ejemplo: 573112229999

merchant_email

String

Condicional

Correo del usuario que genera el cobro.

⚠️ Requerido si se omiten merchant_id_number y merchant_phone.

Ejemplo: alguien@ejemplo.com

attachment

String

Agrega un adjunto que funciona como soporte del cobro.

comments

String

Comentarios o notas de uso interno para tener como referencia al consultar las transacciones.

Comunicación

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

Campo

Tipo

Obligatorio

Descripción

channel

String

Canal por el que se notificará al cliente, bien sea la generación del cobro y/o el comprobante de pago.

ℹ️ Por defecto es enlace de pago (link). WHATSAPP | EMAIL | LINK

user_notification

Boolean

Define si el sistema debe enviar de forma automática la notificación del cobro hacia el usuario final.

ℹ️ Por defecto es false. Si el channel es LINK, no se enviará ninguna notificación. true | false

return_url

String

Enlace al que será redireccionado el usuario de manera automática una vez complete exitosamente el proceso de pago.

ℹ️ No aplica para pagos en chat.

Ejemplo:https://minegocio.com/mi-aplicacion

custom_webhook

String

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.

Ejemplo: https://miwebhook.com/status

Información cliente/pagador `[payer]`

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.

Campo

Tipo

Obligatorio

Descripción

payer.phone

String

Condicional

Número de teléfono celular del cliente pagador (debe incluir el código de área internacional).

⚠️ Es obligatorio si el campo channel está configurado como WHATSAPP y el status del cobro es diferente a CREATED. Ejemplo: 573112223333

payer.email

String

Condicional

Correo del cliente al que se enviarán las notificaciones. ⚠️ Es obligatorio si el campo channel está configurado como EMAIL y el status del cobro es diferente a CREATED. Ejemplo: cliente@minegocio.com

payer.user_id_type

String

Condicional

Tipo de documento de identificación del cliente.

⚠️ Sujeto a la regla de interdependencia. CC | CE | NIT | PASAPORTE | DNI | EIN

payer.user_id_number

String

Condicional

Número del documento de identificación del cliente.

⚠️ Sujeto a la regla de interdependencia. Ejemplo: 11119999

payer.first_name

String

Condicional

Primer nombre del cliente, el cual se usa para la validación del número de documento.

⚠️ Sujeto a la regla de interdependencia. Ejemplo: Andrés

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.

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:

Campo

Tipo

Obligatorio

Descripción

limit_date

Date

Condicional

Es la fecha en la que vence el cobro para el cliente.

⚠️ Si se quieren usar recargos o descuentos, este campo se vuelve estrictamente obligatorio. Formato: AAAA-MM-DD Ejemplo: 2025-01-30

expiration

Boolean

Determina el comportamiento al vencerse el cobro. Si se configura en true, el cobro se cancelará al alcanzar la fecha límite. Por defecto es false. ℹ️ Por defecto es false. true | false

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 [late_fee]: Incrementos aplicados en fechas posteriores a la fecha límite que se suman al valor base.
Descuentos [advance_payment]: 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):

Campo

Tipo

Descripción

AJUSTE.condition_type

String

Indica cómo vas a programar los recargos o descuentos. En esta pestaña aplican los ajustes fijos, es decir, que defines las fechas exactas y los montos a ajustar.

ℹ️ El valor para debe ser estrictamente fixed.

AJUSTE.fixed[].value

Number

Es el monto exacto de dinero que se va a sumar (como recargo) o a restar (como descuento) en esta fecha específica.

Si se envía un valor menor a 1 (Ej: 0.05), se tomará como porcentual. Ejemplo: 5000

AJUSTE.fixed[].date

Date

Fecha exacta hasta la que aplica el recargo o descuento. Formato: AAAA-MM-DD Ejemplo: 2025-01-30

AJUSTE.fixed[].reminder

Boolean

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. ℹ️ Por defecto es false.

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.

Facturación `[invoice]`

Configura la sincronización automatizada de tus transacciones con tu sistema contable preferido.

Campo

Tipo

Obligatorio

Descripción

invoice.provider

String

Condicional

Agrega el software contable con el que realizaste la integración.

⚠️ Obligatorio si envías el objeto invoice. ALEGRA | SIIGO | SAPB1 | SAP4HANA | ODOO

invoice.type

String

Condicional

Elige el tipo de vinculación que quieres realizar para esta transacción con tu software contable.

⚠️ Obligatorio si envías el objeto invoice. LINK | BALANCE | CREATE

invoice.key

String

Indica qué tipo de dato estás enviando en el campo invoice.id.

Valores permitidos:

id: Si el valor es el identificador único interno de tu software.
number: Si estás usando el número consecutivo de la factura (ej: FV-123).

ℹ️ Por defecto toma el valor de id si no lo envías.

invoice.id

String

Corresponde al identificador de la factura o el cliente según el tipo de vinculación definido. Ejemplo: FV-2-1234 | GR1234 | 41515fb0-d815-40ac-86c0-4081eb642fa2

Información de items `[items]`

Desglosa los productos o servicios incluidos en este cobro.

Campo

Tipo

Obligatoria

Descripción

items.code

String

Condicional

Código único que identifica al artículo dentro de tu inventario (SKU o ID interno).

⚠️ Obligatorio si se incluye el arreglo items. Ejemplo: 1050

items.description

String

Condicional

Nombre comercial, detalle o descripción del producto o servicio que se está cobrando.

⚠️ Obligatorio si se incluye el arreglo items. Ejemplo: Correa 20cm

items.unit_of_measure

String

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). Ejemplo: und

items.quantity

Number

Condicional

Cantidad de unidades añadidas de este artículo. Soporta valores decimales en caso de que cobres por peso, medidas o fracciones de tiempo.

⚠️ Obligatorio si se incluye el arreglo items. Ejemplo: 12

items.unit_price

Number

Condicional

Precio por unidad del artículo.

⚠️ Obligatorio si se incluye el arreglo items. Ejemplo: 5000

items.category

String

Categoría a la cual corresponde el artículo.

Ejemplo: Ropa

items.tax_name

String

Nombre técnico o etiqueta del impuesto que aplica a este artículo en específico. Ejemplo: IVA

items.tax_amount

Number

El valor o monto en dinero del impuesto correspondiente a este artículo. Ejemplo: 100

Ubicación `[location]`

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

Campo

Tipo

Obligatorio

Descripción

location.address

String

Dirección de calle, avenida o nomenclatura física del lugar.

Ejemplo: Calle 45 #12-34, Bogotá

location.latitude

String

Coordenada de latitud geográfica del punto de venta o entrega.

Ejemplo: 4.6097

location.longitude

String

Coordenada de longitud geográfica del punto de venta o entrega.

Ejemplo: -74.6097

Recordatorios `[reminders]`

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

Campo

Tipo

Obligatorio

Descripción

reminders[].date

Date

Condicional

La fecha exacta en la que se debe disparar el recordatorio.

⚠️ Obligatorio si se incluye el arreglo reminders. Formato: AAAA-MM-DD Ejemplo: 2025-01-30

reminders[].channel

String

Condicional

El canal a través del cual se enviará el mensaje. WHATSAPP | EMAIL | LINK

reminders[].template

String

Condicional

El nombre o identificador de la plantilla de mensaje preconfigurada.

⚠️ Obligatorio si se incluye el arreglo reminders.

Ejemplo: default

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.

Vendedor `[seller]`

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.

Campo

Tipo

Obligatorio

Descripción

seller.id_number

String

Condicional

Número de documento de identidad oficial del vendedor.

⚠️ Obligatorio si se incluye el objeto seller.

Ejemplo: 12345678

seller.id_type

String

Condicional

Tipo de documento de identidad del vendedor. ⚠️ Obligatorio si se incluye el objeto seller. CC | CE | NIT | PASAPORTE | DNI | EIN

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.

Estos parámetros son de uso exclusivo para plataformas que operan bajo el modelo de cuentas administradas.

Campo

Tipo

Obligatorio

Descripción

custom_saas_fixed

Number

Valor de la comisión fija del administrado aplicable a esta transacción.

ℹ️ Si no se envía, Trazo aplicará automáticamente la tarifa fija por defecto del comercio. Ejemplo: 1000

custom_saas_variable

Number

Valor de la comisión porcentual del administrador aplicable a esta transacción. Debes expresarlo en formato decimal.

ℹ️ Si no se envía, se aplicará la tasa variable por defecto. Ejemplo: 0.02

Response

{
    "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"
}

Ejemplo

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

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();

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)

Última actualización hace 8 días

Endpoint

Headers

Body

Información general

Comunicación

Información cliente/pagador [payer]

Vencimiento y Ajustes Dinámicos

Facturación [invoice]

Información de items [items]

Ubicación [location]

Recordatorios [reminders]

Vendedor [seller]

Tarifas para Cuentas Administradas

Response

Ejemplo

Información cliente/pagador `[payer]`

Facturación `[invoice]`

Información de items `[items]`

Ubicación `[location]`

Recordatorios `[reminders]`

Vendedor `[seller]`