Templates de Cascata (Waterfall)

Pré-requisitos de acesso

• Permissão (módulo): creditConfigManage (para criar/editar). Leitura liberada por viewCredits.
• Licença/Feature: CREDIT_INVESTMENTS habilitada na licença do tenant (Vault).
• Contêiner do menu: TOKENIZAÇÃO → grupo Crédito Tokenizado

O que é / quando usar

O Template de Cascata (Waterfall) define a ordem de distribuição dos recursos quando um recebível é liquidado. Diz, passo a passo, quem recebe primeiro e em que regra: primeiro o principal do investidor, depois o yield do investidor, a taxa da plataforma, eventual excedente do originador e a reserva. É o mecanismo que garante que a cascata de pagamentos siga sempre a mesma prioridade contratada.

Use esta tela para padronizar como o dinheiro liquidado é repartido entre as partes na liquidação (settlement), em vez de definir a ordem caso a caso.

Pré-condições

• Permissão: creditConfigManage (permissão dupla — enum CPM + módulo dinâmico no DB).
• Licença/Feature: CREDIT_INVESTMENTS habilitada.
• Dependências: nenhuma para criar o template; ele é consumido na liquidação (settlement) de uma operação.

Passo a passo

1. Acesse Crédito Tokenizado → Templates de Cascata.
2. Filtre por Ativo se necessário.
3. Clique em Criar.
4. Preencha Nome, % de Reserva e a Regra de Arredondamento.
5. No bloco Passos, clique em Adicionar passo e configure cada linha: Tipo de Item, Tipo de Regra e, se aplicável, o Valor. A ordem é numerada automaticamente (primeiro passo = prioridade mais alta).
6. Reordene removendo/readicionando passos (a renumeração é automática).
7. Clique em Salvar.

Campos

Campo	O que é	Obrigatório?	Efeito no sistema/backend
Nome	Identificação do template	Sim	Gravado em name.
% de Reserva	Percentual retido como reserva antes/durante a cascata	Não (default 0)	Gravado em reservePercentage.
Regra de Arredondamento	Como arredondar valores fracionados: FLOOR (para baixo, 10.9→10), CEIL (para cima, 10.1→11), ROUND (mais próximo)	Não	Gravado em roundingRule (ou null se vazio). Garante consistência de centavos na divisão entre partes.
Passo → Ordem	Posição na fila de distribuição	Sim (automático)	Gravada em order. Na execução, os itens são ordenados por prioridade (menor primeiro) e os repasses ocorrem nessa sequência.
Passo → Tipo de Item	A quem/para quê o passo paga: INVESTOR_PRINCIPAL, INVESTOR_YIELD, PLATFORM_FEE, ORIGINATOR_EXCESS, RESERVE	Sim	Gravado em itemType. Direciona o repasse à conta correta e classifica o lançamento no razão (INVESTOR, PLATFORM ou ORIGINATOR).
Passo → Tipo de Regra	Como o valor do passo é calculado: PERCENT, FIXED ou REMAINDER	Sim	Gravado em rule.type. PERCENT/FIXED usam o Valor; REMAINDER distribui o que sobrou (não usa Valor).
Passo → Valor	Percentual (PERCENT) ou montante (FIXED)	Condicional	Gravado em rule.value. Omitido quando o tipo é REMAINDER.
Ativo	Liga/desliga o template	Sim (default Sim)	Gravado em active.
Versão	Número de versão	Não (default 1)	Gravado em version.

O formulário monta automaticamente o stepsJson (estrutura { steps: [{ order, itemType, rule: { type, value } }] }). Você não edita o JSON manualmente.

Como a cascata é executada (visão do executor)

Na liquidação de um settlement, o executor de waterfall:

1. Localiza a conta do Escrow Pool (pool de garantia da plataforma).
2. Ordena os itens por prioridade (menor número primeiro).
3. Para cada item, libera os fundos do Escrow Pool para a conta destino e registra o lançamento no razão (ledger) com uma idempotencyKey por settlement+itemType.
4. Se um item falhar, o executor continua com os próximos (não aborta a cascata inteira).

Ações e modais

• Criar / Atualizar: grava o template via createWaterfallTemplate / updateWaterfallTemplate. Botão visível só com creditConfigManage.
• Adicionar / Remover passo: manipulam a lista e renumeram a ordem automaticamente.
• Editar: carrega o template e remonta os passos a partir do stepsJson salvo.

Por definir a divisão de dinheiro, salvar pode exigir step-up (senha + MFA) conforme o ambiente.

Regras de negócio / cuidados

Atenção

• A ordem é a prioridade. Quem está em cima recebe primeiro. Coloque sempre INVESTOR_PRINCIPAL antes de INVESTOR_YIELD, e estes antes de PLATFORM_FEE/ORIGINATOR_EXCESS, salvo contrato específico.
• Use REMAINDER no último passo. O passo REMAINDER distribui o saldo remanescente; deixá-lo no meio pode zerar passos seguintes. Normalmente o ORIGINATOR_EXCESS é REMAINDER.
• REMAINDER ignora o Valor. Mesmo que você digite um valor, ele não é gravado para passos REMAINDER.
• Falha parcial não reverte os repasses já feitos. O executor segue para o próximo item; um item que falhou fica pendente sem desfazer os anteriores — exige reconciliação manual.

Distribuição financeira

• A execução da cascata movimenta dinheiro real do Escrow Pool para investidores/plataforma/originador. Uma vez liberado o repasse, não há rollback automático — o template errado distribui errado. Valide a ordem e os valores antes de ativar.

• Valores financeiros: percentuais e montantes são tratados como BigNumber; a Regra de Arredondamento define explicitamente o tratamento de frações de centavo para evitar divergências de reconciliação.
• Idempotência: os repasses são registrados com idempotencyKey por settlement+itemType — reprocessar uma liquidação é seguro e não duplica lançamentos. Em fluxos financeiros do ecossistema, o erro E00021 ("already processed") significa sucesso (já processado), não falha.

Exemplos

Cenário 1 — Cascata padrão investidor-primeiro

1. Nome: "Padrão Sênior". % Reserva: 0. Arredondamento: FLOOR.
2. Passos:
   • 1 · INVESTOR_PRINCIPAL · REMAINDER — devolve o principal investido.
   • 2 · INVESTOR_YIELD · PERCENT · valor conforme yield contratado.
   • 3 · PLATFORM_FEE · PERCENT · taxa da casa.
   • 4 · ORIGINATOR_EXCESS · REMAINDER — o que sobrar volta ao originador.
3. Salvar.

Observação: havendo dois REMAINDER, o primeiro consome o saldo; ajuste para usar FIXED/PERCENT no principal e reservar REMAINDER apenas para o excedente do originador.

Cenário 2 — Cascata com reserva e taxa fixa

1. Nome: "Com Reserva 5%". % Reserva: 5. Arredondamento: ROUND.
2. Passos:
   • 1 · RESERVE · PERCENT · 5.
   • 2 · INVESTOR_PRINCIPAL · FIXED · montante do principal.
   • 3 · INVESTOR_YIELD · PERCENT · yield.
   • 4 · PLATFORM_FEE · FIXED · taxa fixa.
   • 5 · ORIGINATOR_EXCESS · REMAINDER.
3. Salvar.

Resultado: na liquidação, 5% vão para reserva, o principal e o yield do investidor são pagos a seguir, a plataforma recebe a taxa fixa, e o saldo restante volta ao originador.

Cenário 3 — Cascata "originador subordinado"

1. Nome: "Originador Subordinado". Arredondamento: FLOOR.
2. Passos: INVESTOR_PRINCIPAL → INVESTOR_YIELD → PLATFORM_FEE → ORIGINATOR_EXCESS (REMAINDER).
3. Salvar.

Resultado: o originador só recebe excedente depois de todos os investidores e da plataforma — estrutura típica de operação onde o originador absorve a primeira perda.

Telas relacionadas

• Políticas de Crédito
• Templates de Precificação
• Guia de Crédito
• Crédito Tokenizado (índice do grupo)