Billing Portal

Resumo

Infraestrutura completa para você cobrar seus próprios clientes como as big techs: cobranças avulsas, parceladas e recorrentes, assinaturas com trial e pausa, retry inteligente com fallback entre métodos (cartão > PIX > boleto), DDA e Open Finance (Belvo), reconciliação automática, notificações multi-canal, links de pagamento, AI Usage Billing (cobrança medida por tokens) e portal do pagador whitelabel.

Para quem é

• SaaS que cobram assinaturas recorrentes dos próprios clientes
• Empresas B2B com cobranças parceladas e boletos
• Plataformas que revendem IA e precisam cobrar por consumo
• Negócios que querem portal whitelabel para seus pagadores

O que você pode fazer

Cobranças e assinaturas

• Cobranças: avulsas, parceladas ou recorrentes (tab charges).
• Assinaturas: planos com trial, pausa, upgrade/downgrade e métricas de MRR/churn (tab subscriptions).
• Payment Links: links de cobrança com token e expiração (tab payment-links).

Resiliência financeira

• Retry inteligente: RetryService tenta novamente com fallback cartão > PIX > boleto (tab retry).
• Reconciliação automática: ReconciliationService cruza pagamentos com cobranças (tab reconciliation).
• DDA e Open Finance: DDAService integra via Belvo para buscar boletos diretamente do banco (tab dda).

AI Usage Billing

• Cobrança por consumo: AiUsageBillingService mede tokens, chamadas de IA e créditos e gera faturas automáticas.
• Ideal para SaaS que revendem capacidade de IA aos clientes finais.

Comunicação e portal

• Notificações: NotificationService envia por e-mail, WhatsApp e SMS (tab notifications).
• Portal do Pagador: seus clientes acessam um portal whitelabel (views em public/) para ver cobranças, 2ª via, atualizar cartão e baixar recibos.

Configuração

• Geral: configurações globais do portal (tab general).
• Settings: gateways, fallback, regras de retry e preferências (tab settings).

Como começar

1. Em Dashboard > Billing Portal > Configurações, conecte seus gateways.
2. Defina a política de retry em Retry.
3. Crie seu primeiro Link de Pagamento ou Assinatura.
4. Ative notificações em Notificações.
5. Compartilhe o Portal do Pagador com seus clientes.

Tutoriais

Tutorial 1: Criar uma assinatura recorrente

Objetivo: cobrar mensalmente um cliente. Passos:

1. Aba Assinaturas > Nova.
2. Informe o cliente, plano e início.
3. Configure método de pagamento preferido.
4. Acompanhe em Visão Geral (MRR, churn).

Tutorial 2: Configurar retry com fallback

Objetivo: recuperar pagamentos falhos. Passos:

1. Aba Retry.
2. Defina número de tentativas, intervalos e ordem de fallback.
3. Ative notificação ao cliente em cada tentativa.

Tutorial 3: Ativar AI Usage Billing

Objetivo: cobrar por tokens consumidos. Passos:

1. Aba Configurações > AI Billing.
2. Defina preço por 1k tokens, por chamada ou por crédito.
3. Vincule contratos a clientes.
4. O AiUsageBillingService fatura automaticamente ao final do ciclo.

Tutorial 4: Gerar link de pagamento

Objetivo: cobrança rápida por link. Passos:

1. Aba Links de Pagamento > Novo.
2. Informe valor, validade e método.
3. Envie o link por e-mail, WhatsApp ou SMS.

Tutorial 5: Reconciliar pagamentos

Objetivo: identificar quem pagou e quem ficou em aberto. Passos:

1. Aba Reconciliação.
2. Importe extrato OFX ou ative DDA.
3. O serviço cruza automaticamente com cobranças.
4. Revise exceções manualmente.

Integrações com outros plugins

• Business: clientes do CRM viram pagadores do Billing Portal.
• AI-Agents: tokens consumidos por agentes caem no AI Usage Billing.
• Campaign / Automation: cobranças disparam workflows (dunning, notificações).
• Wallet: saldo e créditos conversam com cobranças do Billing.

Perguntas frequentes

Quais métodos de pagamento são suportados? Cartão, PIX, boleto, Open Finance/DDA e gateways de crypto — conforme os gateways configurados em Settings.

Como funciona o retry com fallback? Se uma cobrança no cartão falhar, o RetryService tenta novamente e, se configurado, migra para PIX ou boleto antes de marcar como inadimplente.

Meus clientes acessam um portal próprio? Sim. O Portal do Pagador é whitelabel, exibe histórico, permite baixar 2ª via, atualizar cartão e consultar recibos com a sua marca.

Consigo cobrar por uso de IA? Sim, via AI Usage Billing. Medimos tokens/chamadas/créditos e geramos faturas automáticas por ciclo.

DDA funciona para pessoa jurídica? Sim. Via integração Open Finance (Belvo), o DDAService busca boletos registrados em nome do CNPJ.

Posso usar múltiplos gateways ao mesmo tempo? Sim. Configure fallback entre gateways em Settings para alta disponibilidade.

Como funciona a reconciliação? O ReconciliationService importa extratos e confronta com cobranças emitidas, marcando automaticamente as pagas e sinalizando exceções.

As notificações são personalizáveis? Sim, templates por canal (e-mail, WhatsApp, SMS) com variáveis dinâmicas.

Glossário

• MRR: Monthly Recurring Revenue, receita recorrente mensal.
• Churn: taxa de cancelamento de assinantes.
• DDA: Débito Direto Autorizado, consulta de boletos via bancos.
• Fallback: tentativa alternativa quando o método principal falha.
• AI Usage Billing: cobrança proporcional ao consumo de IA.
• Payment Link: URL autocontida que inicia uma cobrança.

Limitações e avisos

• Taxas e prazos dependem dos gateways configurados.
• DDA via Open Finance exige consentimento do pagador.
• AI Usage Billing exige integração com o Observability e os provedores LLM configurados.
• Notificações via WhatsApp exigem template aprovado na Cloud API.

Relacionados

• Business
• AI-Agents
• Automation
• Campaign