Ejemplos de billing packages del Fees Engine

Recorre escenarios reales de billing packages, desde precios por volumen de boletos hasta cobros de mantenimiento, con configuración completa.

Esta página está orientada al negocio — se enfoca en qué resuelve cada modelo de facturación y cómo configurarlo. Para detalles a nivel de campo, consulta el resumen de Billing Packages y la referencia de API.

​

Facturación por volumen: emisión de boletos con precios escalonados

---

​

La necesidad de negocio

Una fintech ofrece emisión de boletos a sus clientes empresariales. El precio se basa en volumen: cuantos más boletos emita un cliente cada mes, menor será el costo unitario. Los primeros 50 boletos de cada mes son gratuitos. Los clientes que emiten 1,000 boletos o más reciben un descuento adicional del 5%. Con 3,000 boletos o más, el descuento aumenta al 10%.

​

Estructura de precios

Rango	Precio unitario
1–500	R$ 1.20
501–2,000	R$ 0.80
2,001+	R$ 0.45

​

Configuración del paquete

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Boleto Issuance — Tiered",
  "description": "Monthly volume billing for boleto issuance with progressive tiers",
  "ledgerId": "ldg_01HZ...",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "boleto-issuance",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 500, "unitPrice": "1.20" },
    { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.80" },
    { "minQuantity": 2001, "maxQuantity": null, "unitPrice": "0.45" }
  ],
  "freeQuota": 50,
  "discountTiers": [
    { "minQuantity": 1000, "discountPercentage": "5.00" },
    { "minQuantity": 3000, "discountPercentage": "10.00" }
  ],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-operating",
  "creditAccountAlias": "fees-boleto-revenue"
}

​

Cómo funciona el cálculo

Al cierre del mes, el orquestador llama a POST /v1/billing/calculate con el período de facturación. El motor cuenta las transacciones aprobadas de boletos en la ruta, resta la cuota gratuita, aplica los precios escalonados y aplica el descuento correspondiente.

Los precios escalonados son precios por volumen: el motor elige el único nivel en el que cae el conteo facturable y cobra cada unidad facturable al precio de ese nivel. No factura por separado la porción de cada nivel.

Resultado de ejemplo — un cliente que emitió 1,800 boletos en marzo:

Paso	Detalle	Monto
Total emitidos	1,800 boletos	—
Cuota gratuita	50 exentos	—
Facturables	1,750 boletos	—
Nivel aplicado	501–2,000 → R$ 0.80	—
Bruto	1,750 × R$ 0.80	R$ 1,400.00
Descuento	5% (conteo total ≥ 1,000)	−R$ 70.00
Total neto	—	R$ 1,330.00

El motor devuelve un payload de transacción que debita client-operating por R$ 1,330.00 y acredita fees-boleto-revenue.

​

Facturación de mantenimiento: tarifa mensual de cuenta (PF)

---

​

La necesidad de negocio

Un banco digital cobra una tarifa fija mensual de mantenimiento para cuentas personales (PF) activas. La tarifa es de R$ 9.90 por cuenta. El motor conserva solo las cuentas cuyo código de estado es active y excluye cualquier otro estado. No las filtras a mano.

Midaz organiza las cuentas por segmento. El segmento seg_pf agrupa todas las cuentas personales.

​

Configuración del paquete

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active personal accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "seg_pf_01HZ..."
  }
}

​

Cómo funciona el cálculo

El motor resuelve todas las cuentas en el segmento PF y filtra por estado activo. Genera una transacción N:1: debita R$ 9.90 de cada cuenta activa y envía el total completo a fees-maintenance-pf.

Resultado de ejemplo — 12,000 cuentas PF activas:

Detalle	Valor
Cuentas activas	12,000
Tarifa por cuenta	R$ 9.90
Entradas de transacción (origen)	12,000 entradas de débito
Entradas de transacción (destino)	1 entrada de crédito
Ingreso total	R$ 118,800.00

​

Facturación por volumen: Pix a precio fijo con exención por segmento

---

​

La necesidad de negocio

Una fintech cobra R$ 0.10 por cada Pix enviado — tarifa plana, sin niveles. Los clientes de nivel premium no pagan ninguna tarifa. En lugar de listar cada cuenta premium, configuras la exención a nivel de segmento.

​

Configuración del paquete

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Pix Send — Standard",
  "description": "Flat-rate billing per Pix sent",
  "ledgerId": "ldg_01HZ...",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "fixed",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": null, "unitPrice": "0.10" }
  ],
  "freeQuota": 0,
  "discountTiers": [],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-pix-revenue"
}

​

Exención por segmento

Para eximir a las cuentas premium, configura el paquete de tarifas para la ruta pix-send. Agrega una referencia de segmento a waivedAccounts:

{
  "waivedAccounts": [
    "segment:seg_premium_01HZ..."
  ]
}

Todas las cuentas del segmento premium quedan exentas automáticamente. Cuando las cuentas se unen o abandonan el segmento en Midaz, el cambio surte efecto en el siguiente cálculo. No actualizas el paquete.

​

Cómo funciona el cálculo

Resultado de ejemplo — 5,000 transacciones Pix de cuentas estándar:

Detalle	Valor
Total de Pix enviados	5,000
Precio unitario	R$ 0.10
Total	R$ 500.00

Las cuentas premium muestran cero cargos en los resultados de facturación.

​

Facturación de mantenimiento: portfolios PJ con diferentes tarifas

---

​

La necesidad de negocio

Una institución financiera gestiona múltiples portfolios de cuentas empresariales (PJ): PME (pequeñas y medianas empresas) y Corporate. Cada portfolio tiene una tarifa mensual de mantenimiento diferente. La institución quiere calcular ambos en una sola ejecución de facturación.

​

Configuración del paquete

Portfolio PME — R$ 29.90/mes:

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PJ Maintenance — PME",
  "description": "Monthly maintenance for PME business accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "29.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_pme_01HZ..."
  }
}

Portfolio Corporate — R$ 89.90/mes:

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PJ Maintenance — Corporate",
  "description": "Monthly maintenance for Corporate business accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "89.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_corp_01HZ..."
  }
}

​

Cómo funciona el cálculo

Una sola llamada a POST /v1/billing/calculate con "type": "maintenance" procesa ambos paquetes. La respuesta incluye un resultado por paquete y un resumen consolidado.

Resultado de ejemplo — 500 cuentas PME + 50 cuentas Corporate:

Portfolio	Cuentas activas	Tarifa	Total
PME	500	R$ 29.90	R$ 14,950.00
Corporate	50	R$ 89.90	R$ 4,495.00
Consolidado	550	—	R$ 19,445.00

Ambos resultados acreditan la misma cuenta fees-maintenance-pj, manteniendo los ingresos consolidados. El orquestador envía cada payload de transacción a Midaz de forma independiente.

​

Próximos pasos

---

Crear un billing package

Referencia de API para crear billing packages de volumen y mantenimiento.

Calcular facturación

Activar cálculos de facturación para un período y obtener payloads de transacción.

Cálculos de facturación

Mecánicas detalladas de precios escalonados, cuotas gratuitas y facturación de mantenimiento.

Mejores prácticas

Guía operacional para billing packages en producción.