Saltar al contenido principal
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 por mes, menor será el costo unitario. Los primeros 50 boletos de cada mes son de cortesía. Los clientes que emiten más de 1,000 boletos reciben un descuento adicional del 5%; por encima de 3,000, el descuento aumenta al 10%.

​
Estructura de precios

RangoPrecio unitario
1–500R$ 1.20
501–2,000R$ 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:
PasoDetalleMonto
Total emitidos1,800 boletos—
Cuota gratuita50 exentos—
Facturables1,750 boletos—
Nivel 1500 × R$ 1.20R$ 600.00
Nivel 21,250 × R$ 0.80R$ 1,000.00
Subtotal—R$ 1,600.00
Descuento5% (> 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. Las cuentas inactivas, cerradas o suspendidas se excluyen automáticamente — no se requiere filtrado manual. Las cuentas están organizadas por segmento en Midaz. 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, filtra por estado activo y genera una única transacción N:1: cada cuenta activa se debita R$ 9.90, y el total completo va a fees-maintenance-pf. Resultado de ejemplo — 12,000 cuentas PF activas:
DetalleValor
Cuentas activas12,000
Tarifa por cuentaR$ 9.90
Entradas de transacción (origen)12,000 entradas de débito
Entradas de transacción (destino)1 entrada de crédito
Ingreso totalR$ 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 están completamente exentos de esta tarifa. En lugar de listar cada cuenta premium individualmente, la exención se configura 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 (Motor 1) para la ruta pix-send con una referencia de segmento en waivedAccounts: 
{
  "waivedAccounts": [
    "segment:seg_premium_01HZ..."
  ]
}
Todas las cuentas pertenecientes al segmento premium quedan exentas automáticamente. Cuando nuevas cuentas se unen o abandonan el segmento en Midaz, el cambio surte efecto en el siguiente cálculo — no se necesita actualizar el paquete.

​
Cómo funciona el cálculo

Resultado de ejemplo — 5,000 transacciones Pix de cuentas estándar:
DetalleValor
Total de Pix enviados5,000
Precio unitarioR$ 0.10
TotalR$ 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:
PortfolioCuentas activasTarifaTotal
PME500R$ 29.90R$ 14,950.00
Corporate50R$ 89.90R$ 4,495.00
Consolidado550—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.