Valores numéricos (string)
Todos os valores financeiros no Fees Engine devem ser expressos como string, usando o tipo numeric. Isso garante o manuseio decimal de alta precisão para ativos como BRL ou BTC, e previne erros de arredondamento durante cálculos, divisões ou isenções.
Importante
- Requerido: Midaz v3.x.x (usa
numeric).
- Incompatível: Midaz v2.x.x (formato
amount + scale descontinuado).
Clientes usando Midaz v2.x.x devem atualizar para v3.x.x para garantir integração e funcionalidade adequadas com o Fees Engine. Regras de cálculo de taxas
Cada taxa usa uma applicationRule para definir como é calculada. Você pode escolher entre três tipos de regra:
Você pode combinar diferentes regras em um único pacote para atender ao seu caso de uso.
Outros campos importantes:
isDeductibleFrom: define se a taxa é deduzida do remetente ou do destinatário.referenceAmount: pode ser originalAmount ou afterFeesAmount.priority: define a ordem de aplicação. A prioridade 1 deve sempre usar originalAmount.
maxBetweenTypes
Aplica o que for maior: uma taxa fixa ou uma taxa baseada em percentual.
Exemplo
- Valor da taxa fixa: R$5.
- Taxa percentual: 2%.
- Valor de referência: R$1.000.
rate = 1000 * 0.02 = R$ 20,00
flatFee
Aplica um valor fixo de taxa. O comportamento depende do isDeductibleFrom.
Exemplo
- Taxa fixa: R$15.
- Valor de referência: R$115.
isDeductibleFrom | Fórmula | Taxa Total |
|---|
false | referenceAmount + fee | R$ 130,00 |
true | referenceAmount - fee | R$ 100,00 |
percentual
Aplica uma taxa como percentual do valor de referência.
Exemplo
- Valor: 30%.
- Valor de referência: R$ 389,50.
isDeductibleFrom | Fórmula | Taxa Total |
|---|
false | referenceAmount * value | R$ 116,85 |
true | referenceAmount - (referenceAmount * value) | R$ 272,65 |
Divisão de taxas
Quando uma transação tem múltiplas contas de origem, o Fees Engine divide as taxas proporcionalmente.
Exemplo
- Valor total: R$4.000,00
- Taxa fixa: R$15,00
- Imposto: 4%
isDeductibleFrom: false
Participação %
Fórmula: (Valor da Conta ÷ Valor Total) × 100
| Conta | Participação | Valor |
|---|
| @account1 | 25% | R$ 1.000 |
| @account2 | 25% | R$ 1.000 |
| @account3 | 40% | R$ 1.600 |
| @account4 | 10% | R$ 400 |
Distribuição da taxa fixa
Fórmula: taxa fixa × participação %
| Conta | Parcela da Taxa | 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 |
Imposto proporcional
Fórmula: valor da conta × % do imposto
| Conta | Imposto | Total c/ Imposto |
|---|
| @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 |
Valor final por conta
Fórmula: principal + taxa + imposto
| Conta | Taxa | Imposto | 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 |
Validações
- Total das participações = 100%
- Divisão da taxa corresponde à taxa fixa
- Divisão do imposto = 4%
- Total enviado = R$ 4.175,00
Isenções de taxas: regras e hierarquia
Por valor da transação
Use minimumAmount e maximumAmount para definir quando as taxas devem ser aplicadas.
Por exemplo: Se a faixa é R$ 0–300, uma transação de R$ 301 não acionará taxas.
Por conta
O sistema verifica waivedAccounts. Se a origem está listada, ela é isenta de taxas.
Hierarquia: Verificação da faixa de valor > depois isenção por conta
Exemplo misto: isenções de taxas e divisão proporcional de taxas
Vamos ver um exemplo de um pacote que inclui contas com isenções de taxas e requer divisão proporcional das taxas.
Cenário
Estamos processando uma transação de R$ 4.000, que inclui:
- Uma taxa fixa de R$ 16.
- Apenas algumas contas estão sujeitas à taxa fixa.
- Um IOF de 6% a ser deduzido.
Divisão no lado da origem
| Conta de Origem | % | Valor Proporcional |
|---|
| @account1 | 15% | R$ 600 |
| @account2 | 35% | R$ 1.400 |
| @account3 | 40% | R$ 1.600 |
| @account4 | 10% | R$ 400 |
@account3 e @account4.
Resultado após Taxa Administrativa (proporcional)
| Conta | Taxa Admin | Total |
|---|
| @account1 | Isenta | R$ 600 |
| @account2 | Isenta | R$ 1.400 |
| @account3 | R$ 12,80 | R$ 1.612,80 |
| @account4 | R$ 3,20 | R$ 403,20 |
Dedução de IOF (destinatário)
| Destinatário | % | Bruto | IOF (6%) | Líquido |
|---|
| @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 |
As taxas são creditadas nas contas definidas no creditAccount de cada taxa.
Dízimas periódicas
Quando uma divisão de taxa resulta em dízimas periódicas (ex.: 0,3333…), o Fees Engine ajusta automaticamente o primeiro ou maior valor em um centavo para garantir que o total permaneça exato. Isso evita desvios de arredondamento e mantém seu ledger consistente.
