Valores numéricos (string)
Todos los valores financieros en Fees Engine deben expresarse como string, usando el tipo numeric. Esto garantiza el manejo de decimales de alta precisión para activos como BRL o BTC, y previene errores de redondeo durante cálculos, divisiones o exenciones.
Importante
- Requerido: Midaz v3.x.x (usa
numeric).
- Incompatible: Midaz v2.x.x (formato obsoleto
amount + scale).
Los clientes que usen Midaz v2.x.x deben actualizar a v3.x.x para garantizar la integración y funcionalidad adecuadas con el Motor de Tarifas. Reglas de cálculo de tarifas
Cada tarifa usa una applicationRule para definir cómo se calcula. Puedes elegir entre tres tipos de reglas:
Puedes combinar diferentes reglas en un solo paquete para ajustarse a tu caso de uso.
Otros campos clave:
isDeductibleFrom: define si la tarifa se deduce del remitente o del receptor.referenceAmount: ya sea originalAmount o afterFeesAmount.priority: define el orden de aplicación. La prioridad 1 siempre debe usar originalAmount.
maxBetweenTypes
Aplica el mayor valor entre: una tarifa fija o una basada en porcentaje.
Ejemplo
- Valor de tarifa fija: R$5.
- Tarifa porcentual: 2%.
- Monto de referencia: R$1,000.
tasa = 1000 * 0.02 = R$ 20.00
flatFee
Aplica un monto de tarifa fijo. El comportamiento depende de isDeductibleFrom.
Ejemplo
- Tarifa fija: R$15.
- Monto de referencia: R$115.
isDeductibleFrom | Fórmula | Tarifa Total |
|---|
false | referenceAmount + fee | R$ 130.00 |
true | referenceAmount - fee | R$ 100.00 |
percentual
Aplica una tarifa como porcentaje del monto de referencia.
Ejemplo
- Valor: 30%.
- Monto de referencia: R$ 389.50.
isDeductibleFrom | Fórmula | Tarifa Total |
|---|
false | referenceAmount * value | R$ 116.85 |
true | referenceAmount - (referenceAmount * value) | R$ 272.65 |
División de tarifas
Cuando una transacción tiene múltiples cuentas de origen, el Motor de Tarifas divide las tarifas proporcionalmente.
Ejemplo
- Monto total: R$4,000.00
- Tarifa fija: R$15.00
- Impuesto: 4%
isDeductibleFrom: false
Porcentaje de participación
Fórmula: (Monto de Cuenta ÷ Monto Total) × 100
| Cuenta | Participación | Monto |
|---|
| @account1 | 25% | R$ 1,000 |
| @account2 | 25% | R$ 1,000 |
| @account3 | 40% | R$ 1,600 |
| @account4 | 10% | R$ 400 |
Distribución de tarifa fija
Fórmula: Tarifa fija × participación %
| Cuenta | Porción de Tarifa | Total |
|---|
| @account1 | R$ 3.75 | R$ 1,003.75 |
| @account2 | R$ 3.75 | R$ 1,003.75 |
| @account3 | R$ 6.00 | R$ 1,606.00 |
| @account4 | R$ 1.50 | R$ 401.50 |
Impuesto proporcional
Fórmula: monto de cuenta × impuesto %
| Cuenta | Impuesto | Total c/ Impuesto |
|---|
| @account1 | R$ 40.00 | R$ 1,040.00 |
| @account2 | R$ 40.00 | R$ 1,040.00 |
| @account3 | R$ 64.00 | R$ 1,664.00 |
| @account4 | R$ 16.00 | R$ 416.00 |
Monto final por cuenta
Fórmula: principal + tarifa + impuesto
| Cuenta | Tarifa | Impuesto | Total Final |
|---|
| @account1 | R$ 3.75 | R$ 40.00 | R$ 1,043.75 |
| @account2 | R$ 3.75 | R$ 40.00 | R$ 1,043.75 |
| @account3 | R$ 6.00 | R$ 64.00 | R$ 1,670.00 |
| @account4 | R$ 1.50 | R$ 16.00 | R$ 417.50 |
Validaciones
- Total de participaciones = 100%
- División de tarifa coincide con tarifa fija
- División de impuesto = 4%
- Total enviado = R$ 4,175.00
Exenciones de tarifas: reglas y jerarquía
Por monto de transacción
Usa minimumAmount y maximumAmount para definir cuándo deben aplicarse las tarifas.
Por ejemplo: Si el rango es R0–300,unatransaccioˊndeR 301 no activará tarifas.
Por cuenta
El sistema verifica waivedAccounts. Si la fuente está listada, está exenta de tarifas.
Jerarquía: Verificación de rango de valor > luego exención de cuenta
Ejemplo mixto: exenciones de tarifas y división proporcional de tarifas
Veamos un ejemplo de un paquete que incluye cuentas con exenciones de tarifas y requiere dividir las tarifas proporcionalmente.
Escenario
Estamos procesando una transacción de R$ 4,000, que incluye:
- Una tarifa fija de R$ 16.
- Solo algunas cuentas están sujetas a la tarifa fija
- Un impuesto IOF del 6% a deducir.
División en el lado de origen
| Cuenta de Origen | % | Valor Proporcional |
|---|
| @account1 | 15% | R$ 600 |
| @account2 | 35% | R$ 1,400 |
| @account3 | 40% | R$ 1,600 |
| @account4 | 10% | R$ 400 |
Tarifa fija aplicada solo a @account3 y @account4.
Resultado después de Tarifa Administrativa (proporcional)
| Cuenta | Tarifa Admin | Total |
|---|
| @account1 | Exento | R$ 600 |
| @account2 | Exento | R$ 1,400 |
| @account3 | R$ 12.80 | R$ 1,612.80 |
| @account4 | R$ 3.20 | R$ 403.20 |
El valor total de envío aumenta a R$4,016.
Deducción de IOF (destinatario)
| Destinatario | % | Bruto | IOF (6%) | Neto |
|---|
| @donation1 | 25% | R$ 1,000 | R$ 60 | R$ 940 |
| @donation2 | 25% | R$ 1,000 | R$ 60 | R$ 940 |
| @donation3 | 25% | R$ 1,000 | R$ 60 | R$ 940 |
| @donation4 | 25% | R$ 1,000 | R$ 60 | R$ 940 |
Las tarifas se acreditan a las cuentas definidas en el creditAccount de cada tarifa.
Decimales repetidos
Cuando una división de tarifa resulta en decimales repetidos (por ejemplo, 0.3333…), el Motor de Tarifas ajusta automáticamente el primer o mayor valor por un centavo para garantizar que el total permanezca exacto. Esto evita deriva por redondeo y mantiene tu libro mayor consistente.
