Operações de faturamento

Público

Este artigo é para operadores da plataforma GCM. Administradores de igreja devem ver o módulo Doações por organização para as doações de sua congregação — esta página é sobre pagamentos de assinatura para o GCM.

A aba Operações de faturamento (/platform/billing-ops) é onde a equipe resolve tudo que envolve dinheiro: um cartão que foi recusado esta manhã, um cliente que quer reembolso da última fatura, uma renovação que precisa ser empurrada uma semana, um PDF de fatura ausente. Tudo aqui é restrito por superadmin ou platform_admin e cada escrita aterrissa em platform_audit_log com um motivo obrigatório.

A faixa de saúde do cron

Se algum dia você vir uma faixa vermelha no topo dizendo "Cobrança recorrente não está agendada", pare e conserte antes de fazer qualquer outra coisa. Significa que o job charge_recurring não está registrado em pg_cron, então nenhuma renovação dispara até que alguém execute novamente a migração do cron. A faixa só aparece quando o RPC do painel relata cron_health.charge_recurring_scheduled = false — é o alerta mais importante da página.

Os cinco cartões resumo

• MRR estimado — o mesmo número da faixa de KPI das Organizações. Formatado em USD.
• Vence hoje — organizações com subscription_status = 'active' e next_billing_date <= today. Serão cobradas no próximo tick do cron.
• Em atraso — subscription_status = 'past_due'. O contador de tentativas de cada uma fica visível na tabela.
• Tentativas falhas 7d — payment_sessions com status de erro terminal na última semana. Um pico aqui geralmente significa uma indisponibilidade do gateway; verifique o Status no provedor de gateway.
• Reembolsos 30d — contagem de linhas payment_history com status = 'refunded' nos últimos 30 dias.

As quatro sub-abas

Assinaturas

A visão padrão. Cada organização com dados de faturamento, com seu plano, status, próxima data de cobrança, postura de retentativa, cartão registrado e último pagamento bem-sucedido. Os quatro botões de ação por linha são:

• Detalhes — abre a ficha à direita com um detalhamento mais completo, os últimos pagamentos e tentativas recentes do gateway só dessa organização.
• Engrenagem de configurações — abre o diálogo Editar assinatura (coberto abaixo).
• Ícone de atualização — abre o diálogo Renovar / tentar novamente.
• Abrir — fecha esta aba e empurra a ficha de detalhe padrão da organização vinda da página Organizações, para que você possa entrar em personificação ou gestão de equipe.

Pagamentos

O livro-razão de pagamentos. Cada linha em payment_history na plataforma, mais recentes primeiro. Clique no ícone de arquivo para (re)gerar o PDF da fatura — chama adminGenerateInvoice que escreve uma URL assinada na linha. Clique no ícone de seta circular para abrir o Modal de reembolso padrão; é o mesmo componente que o fluxo de doações por organização usa, então reembolsos parciais / completos / fora da plataforma funcionam do mesmo jeito.

Um reembolso só está disponível quando o pagamento está no status approved e o valor é maior que zero. Pagamentos reembolsados e pendentes deixam o botão acinzentado.

Tentativas

Uma visão tarjada de payment_sessions — cada tentativa de transação, bem-sucedida ou não, com o código de resposta do gateway e a mensagem. Esse é o primeiro lugar para olhar quando "o cliente diz que foi cobrado duas vezes": cada tentativa tem um order_identifier que você pode correlacionar com o painel do gateway.

Linha do tempo

Um feed de auditoria rolável restrito a ações de faturamento: edições de assinatura, renovações disparadas, reembolsos processados, faturas geradas. É uma fatia filtrada de platform_audit_log unida aos nomes das organizações — útil quando um cliente pergunta "o que mudou na nossa conta entre terça e sexta?".

Editando uma assinatura

O diálogo Editar assinatura é o painel de sobreposição. Cada campo é editável, mas Motivo é obrigatório (mínimo 3 caracteres) e é anexado à linha de auditoria junto com seu e-mail. Campos:

• Plano e Status — mesmos valores de enum da aba Organizações.
• Fim do trial / Próxima cobrança / Início do ciclo de cobrança — seletores de data. Usados para empurrar ou puxar a próxima cobrança.
• Dia do ciclo de cobrança — 1-31. Se o dia da renovação difere da data de início (por exemplo, cadastrou-se no dia 14 mas cobra no dia 1).
• Limite de membros — inteiro livre. Use quando uma promoção de plano não é apropriada, mas o cliente precisa de margem.
• Contagem de retentativas / Data de retentativa — coloque em zero e limpe a data para parar a tempestade de retentativas em um cartão recusado.
• Pausar até — define a data de retomada quando um cliente pede para suspender o serviço.
• Enviar e-mail ao cliente — interruptor. Desativado por padrão; ative quando a mudança for visível ao cliente (por exemplo, rebaixamento de plano).

Salvar chama adminUpdateSubscription que escreve as novas colunas e insere um evento de auditoria.

Renovando ou tentando novamente

O diálogo Renovar / tentar novamente tem dois modos:

• Apenas pré-visualizar (padrão) — executa a lógica de renovação em simulação. O gateway não é chamado; a resposta mostra o que aconteceria e é despejada em um bloco <pre> para inspeção. Use sempre que estiver em dúvida sobre o estado de um cartão.
• Cobrar agora — invoca de fato o gateway com o token de pagamento armazenado. O botão fica vermelho para que você não clique errado. Um campo de motivo é obrigatório e fica carimbado na linha resultante do histórico de pagamento.

O diálogo bate em adminTriggerRenewal com um requestId novo para que um clique duplicado não cobre duas vezes — a função deduplica no servidor por essa chave.

Cobranças fora do ciclo

Cobrar fora do dia normal de cobrança é OK, mas isso desloca a cadência de renovação: a próxima next_billing_date será calculada a partir de hoje, não da data agendada anteriormente. Se quer manter o ciclo alinhado, edite next_billing_date manualmente de volta no diálogo Editar assinatura depois que a cobrança for bem-sucedida.

Reembolsos

O Modal de reembolso é compartilhado com o fluxo de doações por organização, mas aqui sempre opera em modo administrador de plataforma. Você pode emitir:

• Reembolso pelo gateway — chama o endpoint de reembolso do gateway com o ID da transação original. Os fundos retornam ao cartão do cliente.
• Reembolso fora da plataforma — registra uma linha de reembolso sem tocar o gateway. Use quando você já reembolsou o cliente por transferência / cheque e só precisa que o livro-razão reflita. Os campos manualMethod e referenceNumber são obrigatórios para o auditor poder rastrear.

Um reembolso bem-sucedido escreve em payment_history (status vira refunded), atualiza a linha relacionada em payment_sessions e insere uma entrada platform_audit_log com o motivo.

Situações comuns

"O cartão do cliente foi recusado três noites seguidas e eles querem saber por quê." Abra Detalhes na linha dele, role até as tentativas recentes e leia a mensagem de resposta do gateway. 99% das vezes é INSUFFICIENT_FUNDS, EXPIRED_CARD ou DO_NOT_HONOR. Abra a conta da organização (personifique) e peça para atualizarem o cartão pela página de faturamento voltada ao cliente.

"Precisamos empurrar a renovação uma semana para o cliente fazer uma transferência." Editar assinatura -> defina next_billing_date para hoje + 7. Zere billing_retry_count e limpe billing_retry_at para que a tempestade de retentativas pare. Motivo: "arranjo de transferência, T-7".

"O PDF da fatura está faltando." Aba Pagamentos -> ache a linha -> clique no ícone de arquivo. adminGenerateInvoice re-renderiza o PDF, faz upload para o bucket de faturas e carimba a URL assinada na linha.

"O cron desta manhã não rodou." Cheque primeiro a faixa vermelha. Se ela não está aparecendo mas você suspeita, olhe o número Vence Hoje uma hora depois do horário usual de execução — se não caiu, o job não disparou. A correção é re-executar a migração pg_cron; veja o runbook em docs/runbooks/.