kroz docs
Adaptadores BaaS
Como a kroz traduz regras comerciais em instruções para a instituição de pagamento parceira.
Em resumo
A kroz orquestra regras; o parceiro BaaS licenciado executa Pix, boleto, subcontas e split na origem.
Matriz de rateio (kroz) → adaptador → API do parceiro BaaS
O adaptador é agnóstico de fornecedor: o mesmo desenho de negócio deve funcionar com qualquer IP que atenda os requisitos abaixo.
Requisitos do parceiro BaaS
| Requisito | Por quê |
|---|---|
| Subcontas por recebedor | RC 16 · cada parte identificada na IP |
| Split na origem | Repasse na liquidação, sem conta-bolsão |
| PIX e boleto | Canais do mercado imobiliário |
| Webhooks de liquidação | Conciliação e Rule Engine em tempo real |
| Sandbox homologável | Piloto 72/18/10 sem risco financeiro |
Modelos de liquidação
| Modelo | kroz |
|---|---|
| A · Split na origem | ✅ Desenho adotado |
| B · Conta única + repasses | ⚠️ Exige reavaliação regulatória |
| C · Batch manual pós-pagamento | ❌ Fora do escopo |
O que o adaptador compila
| Entrada (kroz) | Saída (BaaS) |
|---|---|
walletId por recebedor |
Destino no split[] |
| Percentuais da matriz | Alocação na cobrança |
| Pagador (comprador) | Cliente da cobrança · nunca no split |
| Referência do contrato | externalReference rastreável |
| Nº da parcela | Contexto para gatilhos (ex.: 3ª parcela) |
SPE emissora: remainder implícito, não entra como recebedor de split se for a conta emissora.
Dry-run vs execução real
| Modo | Efeito |
|---|---|
| Dry-run (padrão) | Valida matriz, gera payload de preview, sem chamada financeira |
| Real | Cria cobrança/subconta no parceiro BaaS |
Freios operacionais impedem escrita real acidental:
- Confirmação tipada (
CRIAR COBRANCA,CRIAR SUBCONTA…) - Flags habilitadas apenas em ambientes autorizados
- Idempotência obrigatória
Fluxos principais
Cobrança com split
Pagadoria → carregar matriz → validar → gerar cobrança com split[] na criação.
Subconta de recebedor
Oficina de Recebedores → cadastro → subconta na IP → walletId para a matriz.
Transferência pós-liquidação
Quando aplicável (ex.: sweep SPE), orquestrado com mesmos freios de confirmação.
Migração entre parceiros BaaS
O contrato lógico (matriz → split[], walletId, webhook) permanece. O que muda por parceiro:
- Formato exato do payload
- Nomes de eventos de webhook
- Autenticação outbound/inbound
A kroz isola isso na camada adaptador, incorporadoras não reescrevem regra comercial na troca.