Cobranças (Pagadoria)

Gerar sinal, entrada, pré-venda ou parcela com split na origem e mensagem pronta para o corretor.

Em resumo

A Pagadoria (/pagadoria/) emite cobranças PIX com matriz do contrato embutida no payload enviado ao BaaS. Cada recebedor é creditado na subconta na liquidação, split na origem.

Fluxo hero:

Contrato carregado → Tipo de cobrança → Split na origem → Mensagem para o corretor

Pré-requisitos: contrato com matriz no backend, recebedores validados, rateio conferido no Fechamento (recomendado).

Abrir a Pagadoria

Menu: Operação → Pagadoria

Badge no header: Split na origem

Matriz demo exibida no hero: SPE 72% · Landbank 18% · Vendas 10% (CPC 47)

Gerar cobrança: passo a passo

01: Qual cobrança gerar?

Carregar matriz

1. Informe Contrato → ex.: PS-0421
2. Clique Carregar matriz
3. Status: Contrato PS-0421 carregado com matriz v1.
4. SPE emissora preenchida, ex.: Incorp SPE Jardim Oeste
5. Resumo: SPE 72% · Landbank 18% · Vendas 10% · CPC_47_POC

⚠️ Armadilha #1: gerar cobrança sem Carregar matriz → erro Contrato não encontrado ou split inconsistente.

Tipos de cobrança

02: Quem paga e quanto?

Pagador ≠ recebedor. Customer ID é do comprador, não do terrenista ou corretor.

Valores sugeridos (demo PS-0421):

03: Quem está na venda? (opcional)

Campos comerciais, vão para captabilidade (CSV), não para o payload de split.

Copy da UI: Opcional. Registra corretor e imobiliária nesta cobrança, não altera o split nem o link de pagamento.

04: Modo seguro e execução

1. Mantenha toggle ativado no piloto
2. Clique Gerar cobrança
3. Status: Validando pagadoria…
4. Sucesso dry-run: Pagadoria validada em dry-run.
5. JSON de resposta aparece em #pagadoriaResult

Execução real: desativar modo seguro + confirmação tipada no backend (CRIAR COBRANCA). Só após Fechamento aprovado.

Após gerar cobrança

Copiar mensagem para o corretor

1. Clique Copiar mensagem para o corretor
2. Status: Mensagem copiada. Cole no WhatsApp do corretor.
3. Texto inclui link de pagamento e contexto da cobrança

Exportar captabilidade CSV

1. Clique Exportar captabilidade CSV
2. Download: kroz-captabilidade.csv
3. Atribuição comercial (corretor, gerente, imobiliária) por cobrança

Deep link por contrato

A Pagadoria aceita query param:

/pagadoria/?reference=PS-0421

Preenche Contrato e dispara Carregar matriz automaticamente.

Útil vindo da Central ou fila operacional.

O que acontece no backend

Request enviado (resumo):

{
  "dryRun": true,
  "pagadoriaType": "parcela",
  "contractReference": "PS-0421",
  "customerId": "cus_...",
  "value": 50000,
  "dueDate": "2026-07-04",
  "brokerName": "Ana Corretora",
  "billingType": "PIX"
}

API: POST /api/pagadoria-payment com idempotency key.

Evento de auditoria registrado: pagadoria_dry_run_ui ou pagadoria_cobranca_ui.

Split na liquidação

Quando o pagador quita (PIX D+0 ou boleto D+1):

1. BaaS confirma pagamento → webhook
2. Split executa conforme matriz (split[])
3. SPE, terrenista e vendas creditados nas subcontas
4. Evento entra na Governança e, se divergir, na Conciliação

Ver Webhooks (fase 3).

Disclosure BaaS

Rodapé da Pagadoria:

Serviços financeiros prestados pela instituição de pagamento parceira licenciada… A kroz atua exclusivamente como integradora tecnológica e não é instituição financeira.

Na prática

• ✅ Carregar matriz sempre antes de preencher valores
• ✅ Confirmar SPE emissora readonly bate com o contrato
• ✅ Dry-run → revisar JSON → Fechamento → cobrança real
• ✅ Usar Copiar mensagem, evita erro manual no WhatsApp
• ❌ Não usar Customer ID de recebedor
• ❌ Não confundir campos comerciais com split
• ❌ Não desativar modo seguro no piloto

Troubleshooting

Relacionado

• Matriz de rateio, montar e validar regras
• Contratos e unidades, referência de contrato
• Conciliação, pós-liquidação com divergência
• Conceitos, Cobrança
• Conceitos, Split na origem