Billing e Gateways de Pagamento

Resumo

Operação financeira do dia a dia: gateways de pagamento configurados (41+ providers), faturas, pagamentos recebidos, régua de cobrança (dunning), relatórios de uso/consumo, custos de IA e gestão da carteira. Abrange tudo entre emissão da fatura e compensação no gateway.

Para quem é (papel/role)

• super-admin - configura gateways globais e vê operação consolidada.
• tenant-admin - pode ter gateways próprios do tenant (se liberado).

O que você pode fazer

Gateways de pagamento

• Criar / editar gateway: credenciais, webhooks, moedas suportadas, métodos.
• Ativar / desativar gateway.
• Definir gateway padrão: usado quando não há regra específica.
• Testar conexão: valida credenciais sem cobrar cliente.
• Excluir gateway.
• 41+ providers suportados (Stripe, MercadoPago, PagSeguro, Cielo, Revolut, C6Bank, etc).

Faturas (invoices)

• Listar faturas: todas, pagas, pendentes, vencidas, canceladas.
• Detalhe da fatura: itens, impostos, descontos, status.
• Marcar como paga manualmente: baixa manual com descrição auditável.

Pagamentos

• Listar pagamentos: todos, por gateway, por método (pix/cartão/boleto).
• Detalhe do pagamento: status, evidências, estornos.

Dunning (régua de cobrança)

• Fluxos de cobrança: sequências automáticas de e-mail/SMS para faturas atrasadas.
• Tentativas de recobrança: retries com backoff no cartão falho.
• Notificações de vencimento.

Consumo (usage)

• Relatórios de uso: consumo por plano, por feature, por tenant.
• AI costs: custos de IA por tenant/usuário, com base no AiUsageBilling.

Métodos de pagamento

• Configurar métodos: quais métodos aparecem no checkout (pix, cartão, boleto, cripto, carteira).

Resources (recursos cobráveis)

• Gerenciar recursos: items que geram cobrança sob demanda.

Como acessar

1. /admin.
2. Settings → Billing ou /admin/settings/billing.
3. Aba Gateways para configurar providers.
4. Aba Faturas / Pagamentos / Dunning / Usage para operação.

Tutoriais

Configurar Stripe como gateway padrão

1. Acesse /admin/billing/gateways/create.
2. Selecione Stripe e cole as chaves pública e secreta.
3. Configure webhook com a URL gerada pelo sistema.
4. Clique em Testar para validar.
5. Ative e marque como Padrão (/admin/billing/gateways/{id}/set-default).

Dar baixa manual em uma fatura

1. Acesse /admin/settings/billing/invoices.
2. Selecione a fatura pendente.
3. Clique em Marcar como paga e informe método e data.
4. O evento invoice.paid é emitido.

Configurar régua de dunning para cartão falho

1. Acesse /admin/settings/billing/dunning.
2. Crie um fluxo com 3 tentativas (dia 1, 3, 7).
3. Defina templates de e-mail em cada etapa.
4. Ative.

Investigar custo de IA de um tenant

1. Acesse /admin/settings/billing/ai-costs.
2. Filtre pelo tenant desejado.
3. Visualize consumo por provider (OpenAI, Anthropic, etc.) e modelo.

Integrações

• Receita - dados alimentam dashboard (receita-e-financeiro.md).
• Planos - assinaturas geram faturas (planos-e-pacotes.md).
• Afiliados - comissões calculadas sobre faturas pagas (afiliados-admin.md).
• Compliance - dados fiscais seguem retenção legal (compliance-lgpd.md).
• External APIs - chaves de gateway vivem em external-apis-chaves-globais.md.

Perguntas frequentes

Quantos gateways ativos simultâneos são permitidos? Não há limite. Um é padrão; outros podem ser usados por moeda, país ou plano.

Posso ter gateway diferente por tenant? Sim, quando habilitado pelo super-admin.

Reembolso dispara automático no gateway? Sim, via API do provider; se falhar, vai para aprovação manual.

Webhook falhou - como reprocessar? Em Integrations → Webhooks (ver integrations-apis-externas.md).

Posso cobrar em mais de uma moeda? Sim, desde que o gateway configurado suporte.

Dunning pode cobrar por SMS? Sim, se o canal SMS estiver configurado em notificações.

Como testo o fluxo sem cobrar? Use sandbox/test mode do gateway nas credenciais.

E se o webhook chegar antes da confirmação local? A plataforma trata idempotência por payment_intent_id.

Limitações, políticas e avisos

• Chaves de gateway devem ser mantidas em sigilo. Armazenadas criptografadas.
• Ativar gateway sem webhook configurado pode causar atraso na confirmação.
• Marcar fatura como paga manualmente exige justificativa auditável.
• Testes com cartão real são bloqueados em sandbox.

Relacionados

• revenue-and-finance.md
• plans-and-packages.md
• external-apis-global-keys.md
• integrations-external-apis.md