Ejemplos de billing packages del Fees Engine

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 más de 1,000 boletos reciben un descuento adicional del 5%. Por encima de 3,000 boletos, 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": "perAccount",
  "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 por cuenta, resta la cuota gratuita, aplica los precios escalonados y aplica el descuento correspondiente. 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 1	500 × R$ 1.20	R$ 600.00
Nivel 2	1,250 × R$ 0.80	R$ 1,000.00
Subtotal	—	R$ 1,600.00
Descuento	5% (> 1,000 boletos)	−R$ 80.00
Total	—	R$ 1,520.00

El motor devuelve un payload de transacción que debita client-operating por R$ 1,520.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 excluye las cuentas inactivas, cerradas o suspendidas automáticamente. 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": "perAccount",
  "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.

Midaz Core

CRM

Fees

Ejemplos de billing packages del Fees Engine

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

La necesidad de negocio

Estructura de precios

Configuración del paquete

Cómo funciona el cálculo

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

La necesidad de negocio

Configuración del paquete

Cómo funciona el cálculo

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

La necesidad de negocio

Configuración del paquete

Exención por segmento

Cómo funciona el cálculo

Facturación de mantenimiento: portfolios PJ con diferentes tarifas

La necesidad de negocio

Configuración del paquete

Cómo funciona el cálculo

Próximos pasos

Crear un billing package

Calcular facturación

Cálculos de facturación

Mejores prácticas

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

​La necesidad de negocio

​Estructura de precios

​Configuración del paquete

​Cómo funciona el cálculo

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

​La necesidad de negocio

​Configuración del paquete

​Cómo funciona el cálculo

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

​La necesidad de negocio

​Configuración del paquete

​Exención por segmento

​Cómo funciona el cálculo

​Facturación de mantenimiento: portfolios PJ con diferentes tarifas

​La necesidad de negocio

​Configuración del paquete

​Cómo funciona el cálculo

​Próximos pasos

Crear un billing package

Calcular facturación

Cálculos de facturación

Mejores prácticas

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

La necesidad de negocio

Estructura de precios

Configuración del paquete

Cómo funciona el cálculo

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

La necesidad de negocio

Configuración del paquete

Cómo funciona el cálculo

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

La necesidad de negocio

Configuración del paquete

Exención por segmento

Cómo funciona el cálculo

Facturación de mantenimiento: portfolios PJ con diferentes tarifas

La necesidad de negocio

Configuración del paquete

Cómo funciona el cálculo

Próximos pasos