Paquetes de comisiones: workflow por transacción
Los paquetes de comisiones aplican cargos de forma síncrona cuando creas una transacción v2. Esta sección muestra el proceso, desde la configuración de la comisión hasta los resultados.
Paso 1 - Crea tus paquetes de comisiones
Primero, configura los paquetes de comisiones que definen cómo el motor aplica las comisiones. Usa el endpoint Crear un paquete. Cada paquete contiene un conjunto de reglas de comisión y criterios de coincidencia. Puedes adaptar los paquetes a distintos ledgers, segmentos y rutas de transacción mediante estos campos:- transactionRoute - El ID de una ruta de transacción, cuando necesitas coincidencia en el nivel de ruta.
- segmentId - El ID del segmento al que pertenecen las cuentas de origen, cuando necesitas coincidencia en el nivel de segmento.
- metadataSelector - Pares de metadatos que la transacción debe incluir, cuando necesitas coincidencia en el nivel de metadatos.
- Alcance del ledger - La URL de la solicitud identifica qué ledger registra la transacción; no envíes
ledgerIden el cuerpo del paquete. - Monto mínimo y máximo - Umbrales para la aplicación de la comisión.
- routeFrom / routeTo - Definen cómo se mueve cada comisión a través de los flujos contables.
- Listar paquetes - Enumera todos los paquetes creados.
- Obtener un paquete - Obtiene la información de un paquete específico.
- Actualizar un paquete - Actualiza la información de un paquete específico.
- Eliminar un paquete - Elimina lógicamente un paquete.
(opcional) Paso 2 - Ejecuta una estimación
Para previsualizar cómo se comporta un paquete de comisiones antes de confirmar una transacción real, usa el endpoint Estimar comisiones de transacción. Esta estimación ayuda a validar:- Qué reglas de comisión se aplican.
- Cómo se comportará el paquete con los valores indicados.
- Si aplica alguna exención.
Paso 3 - Crea una transacción
Una vez que configures los paquetes, crea la transacción mediante la API de transacciones v2, por ejemplo con el endpoint crear una transacción con el modelo directo v2. Solo las transacciones v2 aplican comisiones, incluidos los elementos directos y de hold de un lote v2. Para coincidir con un paquete limitado a una ruta, envía el ID de la ruta de transacción enrouteId. Midaz lee el segmento de las cuentas de origen.
Paso 4 - Fees Engine evalúa los paquetes
Fees Engine se ejecuta en el mismo proceso cuando Midaz crea la transacción. Evalúa si se aplica un paquete, según:- transactionRoute, cuando está configurado
- segmentId, cuando está configurado
- metadataSelector, cuando está configurado
- El alcance del ledger de la URL de la solicitud
- Monto mínimo y máximo
- waivedAccounts, cuando está configurado para exenciones de comisiones
Fees Engine selecciona como máximo un paquete por transacción: la coincidencia más específica. Cada par de
metadataSelector hace que un paquete sea más específico. Cuando dos paquetes coinciden por igual, Midaz rechaza la transacción con el error 0198.Paso 5 - Verifica las exenciones
El sistema verifica:- Si ningún paquete correspondiente cubre el monto de la transacción.
- Si todas las cuentas de origen están exentas.
0 en un paquete para un rango de montos. Cuando una comisión definida como 0 deja la transacción sin asiento de comisión, los metadatos de la transacción registran feeExemption con el motivo zero_fee_amount, y packageAppliedID indica el paquete.
La cuenta externa (@external/<asset>) que Midaz agrega a una transacción entre ledgers nunca paga comisiones.
Paso 6 - Cálculo y aplicación de la comisión
Si se aplica un paquete, Fees Engine:- Calcula los valores de la comisión según el
applicationRuleseleccionado. - Aplica las comisiones de forma proporcional entre cuentas cuando es necesario.
- Usa
isDeductibleFrompara definir si suma o deduce la comisión. - Enruta las comisiones a la
creditAccountcorrecta mediante los valores configurados derouteFromyrouteTo. - Devuelve el resultado completo de la transacción junto con el
packageAppliedIDen los metadatos.
Paso 7 - Actualizaciones del ledger
Una vez que Fees Engine calcula las comisiones, el componente Transactions se hace cargo. Procesa:- Débitos de las cuentas de origen
- Créditos a los destinos de la comisión
- Desglose de la comisión por ruta y cuenta
Paso 8 - Revisa y confirma
Después de la ejecución, puedes:- Inspeccionar la transacción final y los montos por cuenta.
- Confirmar qué paquete de comisiones se aplicó.
- Verificar todos los movimientos de comisión mediante los metadatos y los registros del ledger.
Fija el precio de un TED o Pix con un contexto de comisión
Un contexto de comisión es una etiqueta que eliges para una transferencia saliente, por ejemplo
ted_salario. Un paquete de comisiones que selecciona por la etiqueta fija el precio de la transferencia. Requiere Midaz 4.2.0 o posterior, con Bank Transfer 3.4.0 o posterior para TED y Pix JD 1.5.0 o posterior para Pix. Las versiones anteriores de los dos plugins rechazan el campo con 400.
Envía la etiqueta en feeContext, en el nivel superior del cuerpo de la solicitud de POST /v1/transfers/initiate para TED y P2P, o de POST /v1/transactions para Pix. La etiqueta es una letra minúscula, seguida de hasta 49 letras minúsculas, dígitos o guiones bajos. Nunca pongas datos personales en ella. Una lectura de la transferencia devuelve feeContext.
Crea el paquete de la etiqueta
Crea el paquete en el ledger del pagador, conmetadataSelector igual a {"feeContext": "<label>"}. La clave es exactamente feeContext.
Midaz aplica el paquete que cumple el mayor número de condiciones. Da al paquete de la etiqueta cada condición del paquete que fija el precio de la misma transferencia sin etiqueta: su transactionRoute, su segmentId y sus pares de metadataSelector. Después agrega el par feeContext. Con menos condiciones, el paquete de la etiqueta puede perder frente a ese paquete o empatar con él, y Midaz rechaza un empate con el error 0198. En la iniciación, Bank Transfer responde 422 BTF-2005.
Cuando el plugin rechaza la etiqueta
Bank Transfer y Pix JD verifican la etiqueta una vez, cuando aceptan la transferencia. Cuando la rechazan, no se retiene nada.
Pix JD también rechaza una etiqueta en una orden que lleva
indirectId, con 400 PIX-0061.
Después de que el plugin acepta la etiqueta
El plugin guarda la etiqueta con la transferencia, y cada intento de registrar la transferencia la lleva. Si deshabilitas o eliminas el paquete después, el plugin no rechaza una transferencia que ya aceptó. Un registro hecho después de eso toma el precio de los paquetes que siguen habilitados. La etiqueta se aplica solo a lo que el pagador envía: el TED OUT, la transferencia P2P y el Pix saliente. Nunca se aplica a un TED o Pix recibido, una devolución o reembolso, MED o Pix Automático. En Bank Transfer, una transferencia P2P entre dos ledgers lleva la etiqueta a los dos ledgers. Cada ledger fija el precio de su propia parte con sus propios paquetes, y en el ledger del destinatario solo se aplica una comisión descontada del monto.¿Por qué estimar una transacción?
Las estimaciones permiten previsualizar cómo se comporta un paquete de comisiones específico, sin ejecutar una transacción real ni escribir en el ledger. Usa las estimaciones cuando:
- Quieres probar un paquete específico.
- Depuras reglas de comisión o umbrales.
- Quieres validar exenciones, rangos de valor o divisiones proporcionales.
- Necesitas una previsualización antes de crear una transacción real.
- Construyes una interfaz y quieres mostrar las comisiones estimadas.
packageId, y el endpoint devuelve lo que ocurriría si se aplicara ese paquete exacto. Una estimación no lee las asignaciones de planes de tarifas.
¿Qué obtienes con una estimación?
- Una estimación completa de las reglas de comisión.
- Qué cuentas cobraría el motor.
- Cómo dividiría el motor la comisión.
- Ningún impacto en el ledger.
Errores comunes
Fees Engine valida cada solicitud para verificar la consistencia y la lógica correcta de las comisiones. A continuación, se muestran los problemas más frecuentes que puedes encontrar al crear paquetes o procesar transacciones.
Paquetes de facturación: workflow por período
Los paquetes de facturación calculan los cargos según el volumen acumulado de transacciones o el mantenimiento por cuenta durante un período de facturación. A diferencia de los paquetes de comisiones, tu orquestador activa la facturación. Decide cuándo calcular y ejecuta los cargos resultantes.
Paso 1: crea los paquetes de facturación
Configura los paquetes de facturación que definen tus reglas de cargo periódicas. Cada paquete es de tipo volumen o mantenimiento. Ejemplo de paquete de volumen, un cargo por cada Pix enviado con precios escalonados:Paso 2: activa el cálculo de facturación
Llama aPOST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate con el período de facturación. La URL identifica el ledger. El motor evalúa cada paquete de facturación habilitado en el ledger, limitado al type que envías.
period admite tres formatos: YYYY-MM (mensual), YYYY-Www (semanal, por ejemplo, 2026-W13) y YYYY-MM-DD (diario).
El campo type es opcional. Usa "volume" o "maintenance" para restringir el cálculo a un solo tipo. Omítelo para calcular ambos tipos en una sola llamada.
Paso 3: recibe los resultados del cálculo
Cada resultado incluye:- El paquete de facturación que lo generó.
- Los montos calculados.
Paso 4: ejecuta los cargos
Envía cadatransactionPayload no vacío a Midaz con Crea una transacción con JSON (POST /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/json) para crear las transacciones de facturación. Un objeto vacío significa que no hay cargo que ejecutar.
El motor de facturación calcula y devuelve resultados. No crea transacciones en Midaz. Tu orquestador controla cuándo y cómo ejecuta los cargos.
Paso 5: revisa y concilia
Después de ejecutar los cargos:- Verifica que las transacciones creadas en Midaz coincidan con los resultados del cálculo de facturación.
- Usa los metadatos de auditoría de los payloads de transacción no vacíos para la conciliación.
- El cálculo de facturación no tiene estado. Una nueva ejecución para el mismo período refleja el ledger en el momento de esa ejecución.
Gestión de paquetes de facturación
Usa estos endpoints para gestionar los paquetes de facturación existentes:GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages: enumera todos los paquetes de facturación.GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{billing_package_id}: obtiene un paquete de facturación específico.PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{billing_package_id}: actualiza un paquete de facturación (sololabel,description,enable).DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{billing_package_id}: elimina lógicamente un paquete de facturación.