- Una tabla de comisiones define cuánta comisión calcular: la moneda, el redondeo y uno o más ítems de comisión (fijo, porcentual, escalonado o basado en expresión).
- Una regla de comisión decide cuándo aplica una tabla de comisiones. Pertenece a un contexto de conciliación, apunta a un lado de coincidencia y lleva predicados que los metadatos de una transacción deben satisfacer. Cuando los predicados coinciden, la regla selecciona su tabla de comisiones.
Qué resuelve el manejo de comisiones
La conciliación falla cuando un lado de una transacción incluye comisiones o cargos que el otro lado no registra. Un gateway de pagos descuenta una comisión de procesamiento antes de liquidar. Un banco cobra una comisión por transferencia. Un adquirente netea comisiones contra los pagos. Sin comisiones modeladas, Matcher trata estas diferencias como discrepancias de monto y genera excepciones, incluso cuando esperas y documentas la diferencia. Las tablas de comisiones describen el cargo, y las reglas de comisión seleccionan cuándo usarlo.
Cómo encajan las reglas y las tablas
Una regla de comisión no contiene el monto de la comisión ni el cálculo en sí. Referencia una tabla de comisiones por ID y la aplica a las transacciones que seleccionan sus predicados.
- Creas una tabla de comisiones una vez en el nivel del tenant. Muchas reglas de muchos contextos pueden reutilizarla.
- Creas una regla de comisión dentro de un contexto. Define un
side, unfeeScheduleId, unpriorityy una lista depredicates. - Cuando Matcher procesa un contexto, evalúa las reglas de comisión del lado relevante en orden de
priority(el más bajo primero). La primera regla que coincide selecciona la tabla referenciada.
feeScheduleId de la regla a ella.
Una regla de comisión por sí sola no cambia los montos de comparación. Los cambia solo cuando el contexto pone
feeNormalization en NET o GROSS, el lado relevante tiene reglas y las monedas de la transacción y de la tabla coinciden. Cuando un contexto tiene reglas de comisión, cada ejecución COMMIT también verifica las transacciones coincidentes contra la comisión esperada y genera excepciones FEE_VARIANCE, FEE_DATA_MISSING o FEE_CURRENCY_MISMATCH.Estructura de la regla de comisión
Una regla de comisión pertenece a un contexto y tiene los siguientes campos.
Predicados
Cada predicado prueba un campo de metadatos de la transacción con un operador.
Operadores disponibles:
Los campos ausentes se evalúan como
false para cada operador excepto EXISTS.
Estructura de la tabla de comisiones
Una tabla de comisiones es una entidad en el nivel del tenant que calcula una comisión a partir de un monto bruto.
Ítems de comisión
Cada ítem declara unname, un priority (orden de aplicación, relevante para CASCADING), un structureType y un structure específico del tipo.
Gestionar las tablas de comisiones
Las tablas de comisiones tienen alcance de tenant y se gestionan de forma independiente de cualquier contexto.
Crear una tabla de comisiones
Esta tabla calcula una comisión de procesamiento del 2.9% sobre el monto bruto, denominada en BRL.cURL
Simular una tabla de comisiones
Antes de conectar una tabla a una regla, simúlala contra un monto bruto para confirmar la comisión calculada.cURL
netAmount, el totalFee y un desglose por ítem.
Una tabla de comisiones no puede eliminarse mientras una regla de comisión o el historial de variación de comisiones la referencie. La solicitud de eliminación devuelve
409 Conflict con el código MTCH-0108. Cuando reglas de comisión bloquean la eliminación, la respuesta lista sus contextos en la entrada de errors[] cuya location es fee-schedule.delete.blocking-contexts. Primero quita o reapunta las referencias de reglas actuales. Las referencias históricas de variación siguen bloqueando la eliminación.Gestionar las reglas de comisión
Las reglas de comisión se crean dentro de un contexto y referencian una tabla de comisiones.
Crear una regla de comisión
Esta regla aplica la tabla de comisiones creada arriba a las transacciones del lado derecho cuyos metadatos deinstitution son iguales a Banco do Brasil.
cURL
Flujo de punta a punta
El manejo de comisiones esperadas sigue tres pasos:
1
Crea la tabla de comisiones
Define una vez cómo se calcula la comisión en el nivel del tenant con
POST /v1/fee-schedules. De forma opcional, valídala con el endpoint de simulación. Anota el id devuelto.2
Crea la regla de comisión en el contexto
Dentro del contexto de conciliación, crea una regla de comisión con
POST /v1/contexts/{contextId}/fee-rules. Pon feeScheduleId en el id de la tabla, elige el side, define un priority único y agrega los predicates que seleccionan las transacciones a las que aplica la comisión.3
Aplícala durante la coincidencia
Pon el
feeNormalization del contexto en NET o GROSS. Luego el contexto necesita al menos una regla de comisión para activarse. Hasta que tenga una, la readiness de activación informa context.activation.requirement.fee-rule. Durante la coincidencia, Matcher evalúa las reglas de cada lado relevante en orden de priority. Una regla que coincide cambia el monto de comparación solo cuando su tabla y la transacción usan la misma moneda.Mejores prácticas
Reutiliza tablas entre contextos
Reutiliza tablas entre contextos
Una tabla de comisiones tiene alcance de tenant y muchas reglas pueden referenciarla. Define una tabla una vez (por ejemplo, “Card Processing - Visa”) y apunta a ella reglas de distintos contextos. Editar la tabla actualiza cada regla que la usa.
Mantén las prioridades únicas e intencionales
Mantén las prioridades únicas e intencionales
Las prioridades son únicas dentro de un contexto y se comparten entre las reglas
LEFT, RIGHT y ANY. Ordénalas de la más específica a la más general para que una regla estrecha gane antes que un respaldo amplio.Acota las reglas con predicados precisos
Acota las reglas con predicados precisos
Los predicados se unen con AND y se prueban contra los metadatos de la transacción. Combina operadores (
EQUALS, IN, BETWEEN, EXISTS) para apuntar exactamente a las transacciones a las que aplica una comisión y evitar atribuciones de comisión no buscadas.Simula antes de conectar una tabla a una regla
Simula antes de conectar una tabla a una regla
Usa
POST /v1/fee-schedules/{scheduleId}/simulate para confirmar que una tabla produce la comisión esperada para montos representativos antes de referenciarla desde una regla.Reapunta las reglas antes de eliminar una tabla
Reapunta las reglas antes de eliminar una tabla
Una tabla referenciada por una regla o por el historial de variación de comisiones no puede eliminarse (
409 MTCH-0108). Cuando reglas de comisión la bloquean, la respuesta lista sus contextos en errors[]. Primero actualiza o quita las referencias de reglas actuales; las referencias históricas de variación siguen bloqueando la eliminación.Próximos pasos
Reglas de coincidencia
Configura cómo Matcher compara transacciones una vez que contabiliza las comisiones esperadas.
Enrutamiento de excepciones
Revisa el comportamiento explícito de asignación, despacho y callback para las excepciones que el manejo de comisiones no cubre.
API de tablas de comisiones
Referencia de API completa de los endpoints de tablas de comisiones.
API de reglas de comisión
Referencia de API completa de los endpoints de reglas de comisión.