Pular para o conteúdo principal
O plugin Bank Transfer divide a configuração em dois níveis. Você pode mudar a maioria das configurações de negócio em tempo de execução, sem reiniciar o serviço. A identidade do tenant e o escopo da organização Midaz servem a propósitos diferentes. Mantenha os dois distintos. Na Lerian Cloud, a claim JWT tenantId no contexto da requisição autenticada identifica o seu tenant, e a Lerian isola os seus dados. O header X-Organization-Id define o escopo da organização Midaz dentro desse tenant. Cada rota de transferência com escopo de organização exige este header, em todos os modos de deploy. Uma requisição retorna 400 se omitir o header ou enviar um valor que não seja um UUID válido.

​
Níveis de configuração

O plugin Bank Transfer tem dois níveis de configuração:
  • Configuração de infraestrutura (o DevOps gerencia) controla URLs, credenciais, configurações de autenticação e timeouts. As mudanças precisam de reinício do serviço.
  • Configurações em tempo de execução (gerenciadas pela Admin API) controlam limites de transferência, políticas de tarifas, horário de funcionamento e roteamento do ledger. As configurações do namespace tenant_policy se aplicam a um tenant. As configurações do namespace runtime_config se aplicam ao deploy inteiro. As mudanças entram em vigor sem reinício do serviço.

​
Decisões de negócio que você pode configurar

GPMs e times de produto se importam com estas configurações. Você as gerencia pela Admin API em tempo de execução, sem deploy, exceto as variáveis de deploy como MIDAZ_FEE_MODE, que mudam apenas com um reinício.

​
Limites de transferência

Defina tetos diários e mensais de valor por tenant com usage_limits.enabled, usage_limits.daily_limit_cents e usage_limits.monthly_limit_cents. O plugin aplica os tetos a cada conta do remetente, sobre o valor debitado do remetente (totalAmount), quando processa uma transferência TED OUT, P2P ou TED entre cores. O dia e o mês reiniciam às 00:00 UTC. Uma transferência acima de um teto é recusada com 422 BTF-0011.

​
Política de tarifas

A variável de deploy MIDAZ_FEE_MODE decide quem calcula e cobra a tarifa de cada transferência TED OUT, TED IN, P2P e TED entre cores:
  • legacy: o plugin-fees calcula a tarifa a partir dos próprios pacotes. O BTF_FEE_ENABLED liga o plugin-fees. Com false, o padrão, o plugin não chama o plugin-fees, e cada transferência roda com tarifa 0.
  • native: o Fees Engine do Midaz 4.1.0 ou posterior calcula e cobra a tarifa a partir dos pacotes de tarifas do ledger. O BTF_FEE_ENABLED não liga nem desliga essa tarifa. Para parar uma tarifa, desabilite o pacote dela no Midaz com enable: false, ou exclua o pacote.
  • auto (padrão): native no Midaz 4.1.0 ou posterior, e legacy em uma versão anterior ou quando a primeira leitura da versão falha.
Com auto, uma atualização do Midaz para a 4.1.0 ou posterior passa o Bank Transfer para native sozinho. Se seus pacotes de tarifas ainda estão no plugin-fees, o Midaz não encontra nenhum pacote, e as transferências novas ficam sem tarifa. Defina MIDAZ_FEE_MODE=legacy antes de atualizar o Midaz e depois siga Migrar as tarifas do Bank Transfer para o Midaz.
No modo native, uma iniciação pode levar um rótulo de tarifa opcional em feeContext: uma letra minúscula, seguida de até 49 letras minúsculas, dígitos ou sublinhados. Um pacote de tarifas no ledger do pagador seleciona por ele. O plugin verifica o rótulo uma vez, na iniciação. Ele recusa a iniciação com 422 BTF-0008 quando nenhum pacote de tarifas no ledger do pagador seleciona pelo rótulo, habilitado ou não, ou quando o ledger não calcula tarifas de forma nativa. Os lançamentos da transferência no ledger levam o rótulo, e Get Transfer o retorna.

​
Fail-open vs. fail-closed

No modo legacy, a política de tenant fees.fail_closed_default (padrão false) decide o que uma falha do plugin-fees faz:
  • TED OUT e P2P: quando o plugin-fees está indisponível, a transferência segue sem tarifa (fail-open). Com true, o plugin recusa a transferência (fail-closed). Uma tarifa que o plugin-fees recusa sempre recusa a transferência.
  • TED IN: qualquer falha de tarifa credita os fundos com tarifa 0. Com true, o plugin não credita e devolve a transferência ao banco de origem.

​
Recebimento de TED IN

O polling de TED IN fica desligado por padrão. O DevOps o liga para o deploy com JD_POLLING_ENABLED=true, depois que as credenciais JD SPB estiverem configuradas. Quando o plugin não encontra o destinatário de um TED IN, a política de tenant jd_polling.auto_return_authorized (padrão false) decide se ele devolve os fundos ao banco de origem ou retém a mensagem para um operador. Veja Receber (TED IN).

​
Horário de funcionamento

Cada tenant tem uma janela de TED OUT: operating_hours.window (HH:MM-HH:MM, padrão 06:30-17:00) no fuso de operating_hours.timezone (padrão America/Sao_Paulo). O plugin recusa um TED OUT fora da janela, nos fins de semana e nos feriados do BACEN com 422 BTF-0010. A mesma janela vale para a devolução de um TED IN, que também fecha no máximo às 13:00 em 24 de dezembro e no último dia útil do ano. O P2P ignora a janela.

​
Roteamento do ledger

A política de tenant routing.ledger_bindings é um único documento JSON que vincula cada organização Midaz, ledger e tipo de transferência às suas rotas contábeis. Um vínculo ou nomeia as rotas de transação e de operação do Midaz a usar, ou define mode: omit para lançar sem rotas. Não existe fallback de um vínculo para outro. Sem um vínculo:
  • TED OUT e P2P são recusados com 503 BTF-9015. O erro nomeia a configuração ausente em systemplaneKey e a causa em reason.
  • Um TED IN fica retido com o motivo LEDGER_ROUTE_UNRESOLVED. O plugin o credita assim que o vínculo existir.
Cada tipo de crédito ao cliente (TED_IN_STR0005 a TED_IN_STR0051) precisa do próprio vínculo, separado de TED_IN. A devolução de um TED IN é lançada no vínculo de TED_OUT do ledger do TED IN. Um TED entre cores é lançado no vínculo de CROSS_CORE_OUT. Um crédito entre cores recebido do outro core é lançado em CROSS_CORE_IN, e a devolução de um TED entre cores que você enviou é lançada em CROSS_CORE_RETURN_IN. Antes de mover tráfego, chame Check Ledger Routing Readiness. A resposta traz ready: true apenas quando cada organização, ledger e tipo de transferência em uso tem um vínculo, e cada rota nomeada existe no Midaz.

​
Configuração de infraestrutura

O DevOps define as variáveis de ambiente do momento do deploy (URLs, credenciais, TLS, persistência, integrações, chaves de segurança). Essas variáveis exigem reinício do serviço. Veja a referência completa em Variáveis de ambiente.

​
Configuração em tempo de execução (Admin API)

Você gerencia as configurações em tempo de execução pela Admin API em /system/:namespace/:key, sem reinício. As chaves de política de tenant ficam no namespace tenant_policy. As chaves do deploy inteiro ficam em runtime_config. As configurações ajustáveis incluem:
  • Limites de transferência (diários e mensais, por tenant)
  • Comportamento de tarifa (fees.fail_closed_default, fees.max_fee_amount_cents, fees.refund_on_devolucao)
  • Devoluções de TED IN quando o destinatário não é encontrado (jd_polling.auto_return_authorized)
  • Horário de funcionamento (operating_hours.window, operating_hours.timezone)
  • Roteamento do ledger (routing.ledger_bindings)
  • P2P entre dois ledgers de uma organização (p2p.cross_ledger_enabled). Veja Transferências entre ledgers
  • Um ISPB que você compartilha com outro core da sua instituição (onus.shared_ispb_gate_enabled). Veja Transferências entre cores

​
Configurações gerenciadas pelo systemplane

O systemplane (Admin API) gerencia as configurações abaixo em tempo de execução, não no momento do deploy. O plugin ignora essas variáveis de ambiente: se você definir uma delas, ele registra o WARN systemplane-managed environment variable is set and ignored. Use o systemplane para mudá-las.
Quando o CORS não está configurado, a origem permitida padrão é o coringa *. Qualquer origem pode então chamar a API, e o plugin não a valida na inicialização. Para produção, defina origens explícitas pela chave cors.allowed_origins do systemplane, em vez do coringa.