Crear cuenta administrada

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

POST /v1/business/child

Encabezado

Name	Value
Content-Type*	application/json
x-auth-token*	{token}

Cuerpo

Datos del Negocio

Name	Type	Description
business_id*	string	Es el identificador único que se le asignará al negocio hijo en el sistema
business_name*	string	Nombre comercial de la sede o del sub-negocio.
type*	string	Categoría del negocio. general | logistic
business_id_type*	string	Tipo de documento de identificación del negocio. CC | CE | NIT | PASAPORTE | DNI | EIN
business_id_number*	string	Número de identificación de la empresa (NIT sin DV).
business_id_number_dv	numeric	Dígito de verificación de la empresa Ejemplo: 1
business_phone	string	Número de celular del negocio. Ejemplo: 573112229999
business_email	string	Correo electrónico de contacto comercial del sub-negocio. Ejemplo: [e-mail]
business_webhook	string	URL del webhook donde el sub-negocio recibirá los eventos de notificación. Ejemplo:https://minegocio.com/mi-aplicacion

Datos de Contacto (Usuario Principal)

Están relacionados directamente con la persona que será el contacto principal de este sub-negocio:

Name	Type	Description
first_name	string	Nombre del contacto principal.
last_name	string	Apellido del contacto principal.
nickname	string	Apodo o nombre corto para el contacto.
phone	string	Número de teléfono móvil del contacto principal (debe tener entre 10 y 15 dígitos numéricos).
user_email	string	Correo electrónico válido del contacto.
user_id_type	string	Tipo de documento de identificación del contacto principal. CC | CE | NIT | PASAPORTE | DNI | EIN
user_id_number	string	Número de identificación del usuario.
user_id_number_dv	number	Dígito de verificación del documento del usuario (opcional, por defecto es null).

Apariencia y Ubicación

Campos adicionales que permiten que el hijo tenga su propio estilo y ubicación geográfica separada del padre:

Name	Type	Description
logo	string	URL (URI válida) con la imagen del logo del sub-negocio.
main_color_brand	string	Código HEX del color principal de la marca Ejemplo #FF0000
secondary_color_brand	string	Código HEX del color secundario de la marca. Ejemplo #FF0000
city	string	Ciudad principal de operación.
state	string	Departamento o estado provincial de operación.
country	string	País de operación.

Configuración Financiera

Name	Type	Description
fee_variable_saas	number	Tarifa (fee) variable aplicada bajo el modelo SaaS para este sub-negocio específico. Se espera un número entre 0 y 1(por defecto es 0 Ejemplo: 0.1
fee_fixed_saas	number	Tarifa (fee) fija aplicada bajo el modelo SaaS para este sub-negocio específico. Ejemplo: 2000

Configuración Medios de Pago

Name	Type	Description
payment_methods.breb	boolean	Habilita los pagos mediante Bre-B.
payment_methods.wallet	boolean	Habilita los pagos mediante billetera digital.
payment_methods.bank	boolean	Habilita los pagos mediante transferencia bancaria.
payment_methods.card	boolean	Habilita los pagos con tarjeta nacional.
payment_methods.card_intl	boolean	Habilita los pagos con tarjeta internacional.
payment_methods.card_by_tz	boolean	Habilita los pagos con tarjeta mediante zona tarifaria.
payment_methods.cash	boolean	Habilita los pagos en efectivo.

Verificación del Negocio (KYB)

Flujo SELF: Sin objeto compliance

La cuenta administrada realiza su propia vinculación.

El kyb_url contiene un token con datos del partner. Incluye logo, colores y URL de retorno. El enlace se acorta automáticamente para facilitar su distribución.

Flujo PARENT: Con compliance.type: "PARENT"

La cuenta padre asume la vinculación del comercio. Un aprobador registrado acepta los documentos legales desde un portal controlado por Trazo.

Configuración Aprobación de la Cuenta Administrada

La aceptación de documentos legales no está disponible vía API. Debe realizarse desde Webviews de Trazo.

Name	Type	Required	Description
compliance.type	string	Sí	Tipo de compliance. Actualmente solo admite PARENT.
compliance.approver_id	string	Sí	Número de identificación del aprobador registrado en el equipo del negocio padre.
compliance.channel	string	Sí	Canal de envío de la solicitud. Actualmente solo admite EMAIL.

El objeto compliance es opcional. Si no se envía, se usa el flujo SELF.

Email automático

Con compliance.type en PARENT, se envía un email al aprobador.

Respuesta

200 — SELF

{
  "message": "cuenta administrada creada exitosamente",
  "business_id": "PAY-CHILD-001",
  "status": "PENDING_COMPLIANCE",
  "kyb_url": "https://tz.co/abc123",
  "managing_business_id": "PAY-001",
  "created_at": "2026-07-23T13:00:00-05:00"
}

200 — PARENT

{
  "message": "cuenta administrada creada exitosamente",
  "id": "ma_PAY-CHILD-002",
  "business_id": "PAY-CHILD-002",
  "status": "PENDING_APPROVAL",
  "compliance_type": "PARENT",
  "approver": {
    "id": 42,
    "email": "[e-mail]",
    "name": "Carlos Gómez"
  },
  "managing_business_id": "PAY-001",
  "created_at": "2026-07-23T13:00:00-05:00"
}

200 — PARENT sin aprobador

{
  "message": "cuenta administrada creada exitosamente",
  "id": "ma_PAY-CHILD-002",
  "business_id": "PAY-CHILD-002",
  "status": "PENDING_APPROVAL",
  "compliance_type": "PARENT",
  "approver": null,
  "managing_business_id": "PAY-001",
  "created_at": "2026-07-23T13:00:00-05:00"
}

400

{
    "error": [
        "\"fee_variable_saas\" must be a number"
    ]
}

401

{
    "status": "unauthorized",
    "code": "Q103",
    "error": "El x-auth-token se encuentra vencido. Por favor genera un nuevo token y reintenta de nuevo el cobro."
}

---

Ejemplo

cURL

El partner asume el compliance del comercio

curl --location '{{base_url}}/v1/business/child' \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-auth-token: YOUR_SECRET_TOKEN' \
--data '{
  "business_id": "PAY-CHILD-002",
  "business_name": "Zona Sur",
  "type": "general",
  "business_id_type": "NIT",
  "business_id_number": 901234567,
  "phone": "573009876543",
  "first_name": "María",
  "last_name": "López",
  "nickname": "María",
  "user_id_type": "CC",
  "user_id_number": "87654321",
  "user_email": "[e-mail]",
  "business_email": "[e-mail]",
  "compliance": {
    "type": "PARENT",
    "approver_id": "12345678",
    "channel": "EMAIL"
  }
}'

Con medios de pago y branding personalizado

curl --location '{{base_url}}/v1/business/child' \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-auth-token: YOUR_SECRET_TOKEN' \
--data '{
  "business_id": "PAY-CHILD-003",
  "business_name": "Café del Centro",
  "business_official_name": "Café del Centro SAS",
  "type": "general",
  "business_id_type": "NIT",
  "business_id_number": 901987654,
  "phone": "573115551234",
  "first_name": "Ana",
  "last_name": "Rodríguez",
  "nickname": "Ana",
  "user_id_type": "CC",
  "user_id_number": "55667788",
  "user_email": "[e-mail]",
  "business_email": "[e-mail]",
  "logo": "https://cdn.ejemplo.com/cafe-centro-logo.png",
  "main_color_brand": "#2D5016",
  "secondary_color_brand": "#F5E6D3",
  "city": "Bogotá",
  "state": "Bogotá D.C.",
  "country": "Colombia",
  "fee_variable_saas": 0.02,
  "fee_fixed_saas": 500,
  "payment_methods": {
    "breb": true,
    "wallet": true,
    "bank": true,
    "card": true,
    "card_intl": false,
    "card_by_tz": false,
    "cash": true
  },
  "compliance": {
    "type": "PARENT",
    "approver_id": "12345678",
    "channel": "EMAIL"
  }
}'

La cuenta administrada hace su propio KYB

curl --location '{{base_url}}/v1/business/child' \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-auth-token: YOUR_SECRET_TOKEN' \
--data '{
  "business_id": "PAY-CHILD-001",
  "business_name": "Zona Norte",
  "business_official_name": "Gran Logística SAS",
  "type": "general",
  "business_id_type": "NIT",
  "business_id_number": 901234567,
  "phone": "573001234567",
  "first_name": "Juan",
  "last_name": "Pérez",
  "nickname": "Juan",
  "user_id_type": "CC",
  "user_id_number": "12345678",
  "user_email": "[e-mail]",
  "business_email": "[e-mail]"
}'

NodeJS (Axios)

const axios = require('axios');
let data = JSON.stringify({
  "phone": "",
  "first_name": "",
  "last_name": "",
  "nickname": "",
  "user_id_type": "",
  "user_id_number": "",
  "user_email": "",
  "user_id_number_dv": null,
  "type": "general",
  "business_id": "",
  "business_name": "",
  "business_id_type": "",
  "business_id_number": 1,
  "business_id_number_dv": 1,
  "business_url": "",
  "business_phone": "",
  "business_webhook": "",
  "business_email": "",
  "logo": null,
  "main_color_brand": null,
  "secondary_color_brand": null,
  "city": null,
  "state": null,
  "country": null,
  "fee_variable_saas": 0
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: `${base_url}/v1/business/child`,
  headers: { 
    'Content-Type': 'application/json', 
    'x-auth-token': token
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python

import requests
import json

url = f"{base_url}/v1/business/child"

payload = json.dumps({
  "phone": "",
  "first_name": "",
  "last_name": "",
  "nickname": "",
  "user_id_type": "",
  "user_id_number": "",
  "user_email": "",
  "user_id_number_dv": None,
  "type": "general",
  "business_id": "",
  "business_name": "",
  "business_id_type": "",
  "business_id_number": 1,
  "business_id_number_dv": 1,
  "business_url": "",
  "business_phone": "",
  "business_webhook": "",
  "business_email": "",
  "logo": None,
  "main_color_brand": None,
  "secondary_color_brand": None,
  "city": None,
  "state": None,
  "country": None,
  "fee_variable_saas": 0
})
headers = {
  'Content-Type': 'application/json',
  'x-auth-token': token
}

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

print(response.text)