Gestão de Métodos de Pagamento

O sistema de Métodos de Pagamento do OmniCRM permite que clientes e funcionários gerenciem cartões de pagamento de forma segura usando processamento de pagamento de múltiplos fornecedores (Stripe, PayPal, etc.). Os métodos de pagamento possibilitam faturamento automático para serviços, pagamentos únicos e cobranças recorrentes sem armazenar dados sensíveis do cartão no OmniCRM.

Veja também: Payment System Guide <payment_system_guide>, Billing Overview <billing_overview>, Payment Processing <payments_process>, Invoices <payments_invoices>.

Visão Geral

O sistema de métodos de pagamento fornece:

• Armazenamento Seguro de Cartões - Cartões tokenizados por fornecedores de pagamento (Stripe, PayPal), nunca armazenados no OmniCRM
• Suporte a Múltiplos Fornecedores - Métodos de pagamento Stripe e PayPal suportados
• Vários Cartões - Clientes podem armazenar múltiplos métodos de pagamento
• Seleção Padrão - Designar método de pagamento preferido para cobranças automáticas
• Rastreamento de Vencimento - Monitorar e atualizar cartões que estão prestes a vencer
• Autoatendimento - Clientes podem gerenciar seus próprios cartões através do Self-Care Portal <self_care_portal>
• Gerenciamento de Funcionários - Funcionários de suporte podem adicionar/remover cartões em nome dos clientes

Métodos de Pagamento Suportados:

• Cartões (via Stripe ou PayPal)
  • Cartões de Crédito (Visa, Mastercard, American Express, Discover)
  • Cartões de Débito
  • Cartões Pré-pagos (se suportados pela rede de cartões)
• Contas do PayPal (via integração com o PayPal)

Não Armazenado no OmniCRM:

Os detalhes do cartão são tokenizados pelos fornecedores de pagamento e armazenados de forma segura. O OmniCRM apenas armazena:

• Fornecedor de pagamento (stripe, paypal)
• Marca do cartão (Visa, Mastercard, etc.)
• Últimos 4 dígitos
• Mês/ano de vencimento
• Nome/nome de usuário do titular do cartão
• Token do método de pagamento específico do fornecedor

Acessando Métodos de Pagamento

Da Página do Cliente:

1. Navegue até Clientes → [Selecionar Cliente]
2. Clique na aba Faturamento
3. Role até a seção Métodos de Pagamento

Ou diretamente:

Do Painel de Cartões Vencendo:

Veja todos os clientes com cartões que estão prestes a vencer:

Isso mostra uma lista de cartões que estão vencendo em até 60 dias.

Lista de Métodos de Pagamento

A tabela de métodos de pagamento exibe todos os cartões armazenados para um cliente:

Descrições das Colunas:

• Nome de Usuário - Nome amigável para o cartão (por exemplo, "Cartão Pessoal", "Visa de Trabalho")
• Emissor - Marca do cartão e últimos 4 dígitos
• Vencimento - Mês/ano de expiração (formato MM/YYYY)
• Adicionado - Data em que o cartão foi adicionado à conta
• Padrão - Marca de seleção indica o método de pagamento padrão para cobranças automáticas

Ações por Cartão:

Cada linha tem um menu de ações (⋮) com opções:

• Definir como Padrão - Tornar este o método de pagamento padrão
• Excluir - Remover cartão da conta

Adicionando um Método de Pagamento

Clique em "Adicionar Método de Pagamento" para abrir o modal de pagamento seguro.

Passo 1: Inserir Detalhes do Cartão

O formulário de pagamento seguro aparece (alimentado por Stripe Elements ou PayPal SDK):

Campos Obrigatórios:

• Informações do Cartão - Número do cartão, vencimento, CVC (validado pelo Stripe)
• Nome do Titular do Cartão - Nome no cartão
• País/Região - País de faturamento

Campos Opcionais:

• Nome de Usuário do Cartão - Rótulo amigável para distinguir entre cartões

Segurança:

• Detalhes do cartão inseridos diretamente em um iframe seguro hospedado pelo fornecedor (Stripe Elements / PayPal SDK)
• O OmniCRM nunca vê ou armazena números de cartões completos
• Conformidade com PCI DSS gerenciada pelo fornecedor de pagamento
• Validação em tempo real impede números de cartões inválidos

Passo 2: Enviar e Tokenizar

Quando você clica em "Adicionar Método de Pagamento":

1. Validação do Lado do Cliente:
   • O fornecedor de pagamento valida o formato do número do cartão
   • Verifica se a data de vencimento está no futuro
   • Verifica o formato do CVC
2. Tokenização:
   • Detalhes do cartão enviados diretamente ao fornecedor de pagamento (não ao OmniCRM)
   • O fornecedor cria um token seguro (por exemplo, pm_1A2B3C4D para Stripe)
   • Token retornado ao OmniCRM
3. Processamento no Servidor:
   • O OmniCRM salva o token no registro do cliente com o identificador do fornecedor
   • Armazena os últimos 4 dígitos, marca, vencimento e nome do fornecedor para exibição
   • Nenhum número de cartão completo toca nos servidores do OmniCRM

Passo 3: Confirmação

Mensagem de sucesso aparece:

Seu Visa terminando em 1234 foi adicionado à sua conta.

O novo cartão aparece na tabela de métodos de pagamento.

Seleção Automática Padrão:

• Se este for o primeiro cartão do cliente, ele é automaticamente definido como padrão
• Se o cliente já tiver cartões, o novo cartão é adicionado como não padrão
• O cliente pode alterar o padrão após a adição

Definindo o Método de Pagamento Padrão

O método de pagamento padrão é usado para:

• Cobranças automáticas de serviços recorrentes
• Pagamentos de faturas
• Recargas e reabastecimentos
• Transações únicas (a menos que especificado de outra forma)

Para Alterar o Padrão:

1. Localize o cartão que deseja definir como padrão na tabela de métodos de pagamento

2. Clique no menu de ações (⋮) ao lado do cartão

3. Selecione "Definir como Padrão"

4. A confirmação aparece

   O Visa terminando em 5678 agora é seu método de pagamento padrão.

A marca de seleção se move para o cartão recém-selecionado.

Indicador Visual:

Cartões padrão mostram:

na coluna Padrão, tipicamente com um distintivo de marca de seleção verde.

Excluindo um Método de Pagamento

Remova cartões que estão expirados, perdidos ou que não são mais necessários.

Passo 1: Iniciar Exclusão

1. Encontre o cartão a ser excluído na tabela de métodos de pagamento
2. Clique no menu de ações (⋮)
3. Selecione "Excluir"

Passo 2: Confirmar Exclusão

Um modal de confirmação aparece:

Você tem certeza de que deseja excluir este método de pagamento?

Cartão: Visa terminando em 1234 Vencimento: 12/2026

⚠️ Aviso: Se este for seu único método de pagamento, você precisará adicionar um novo para continuar usando serviços que requerem faturamento automático.

[Cancelar] [Excluir Método de Pagamento]

Clique em "Excluir Método de Pagamento" para confirmar.

Passo 3: Exclusão Completa

Mensagem de sucesso:

O cartão é removido da tabela e excluído do fornecedor de pagamento.

Restrições Importantes:

• Não é possível excluir o padrão se outros cartões existirem - Defina um cartão diferente como padrão primeiro
• Aviso se excluir o último cartão - Serviços que requerem pagamento podem ser suspensos
• Sem desfazer - A exclusão é permanente; o cliente deve re-adicionar o cartão se necessário

Gerenciando Cartões Vencendo

O OmniCRM rastreia as datas de vencimento dos cartões e fornece ferramentas para atualizar proativamente os cartões que estão prestes a vencer.

Painel de Cartões Vencendo

Navegue até Faturamento → Cartões Vencendo para ver uma lista em todo o sistema:

Cliente Cartão Vencimento Dias até Ação John Smith Visa **1234 02/2025 12 dias Atualizar Acme Corp MC5678 03/2025 45 dias Atualizar Jane Doe Amex**9012 01/2025 VENCIDO Atualizar

Filtros:

• Faixa de Vencimento - Próximos 30/60/90 dias ou já expirados
• Tipo de Cliente - Individual vs Empresarial
• Tipo de Serviço - Filtrar por serviço que requer método de pagamento

Ações:

• Atualizar - Abre a página de métodos de pagamento do cliente para adicionar um novo cartão
• Notificar - Enviar lembrete por e-mail ao cliente (se Mailjet configurado)

Notificações de Vencimento

Se o Mailjet estiver configurado, e-mails automáticos são enviados:

• 60 dias antes do vencimento - Primeiro lembrete
• 30 dias antes do vencimento - Segundo lembrete
• 7 dias antes do vencimento - Aviso final
• No vencimento - Aviso de que o cartão expirou

Os clientes podem clicar em um link no e-mail para atualizar seu método de pagamento através do portal de Autoatendimento.

Variáveis do Modelo de E-mail:

Os modelos do Mailjet recebem:

• Nome do cliente
• Marca do cartão e últimos 4 dígitos
• Data de vencimento
• Link para a página de métodos de pagamento do Autoatendimento

Veja integrations_mailjet para configuração do modelo de e-mail.

Atualizando um Cartão Vencendo

Fluxo de Trabalho Recomendado:

1. O cliente recebe um e-mail de notificação de vencimento
2. O cliente faz login no portal de Autoatendimento
3. Navega até Faturamento → Métodos de Pagamento
4. Clica em "Adicionar Método de Pagamento"
5. Insere os novos detalhes do cartão (mesmo cartão com vencimento atualizado ou cartão de substituição)
6. Define o novo cartão como padrão
7. Exclui o cartão antigo/vencido

Fluxo de Trabalho do Funcionário:

Se o cliente ligar para o suporte:

1. O funcionário abre a conta do cliente
2. Navega até Faturamento → Métodos de Pagamento
3. Adiciona um novo cartão em nome do cliente (o cliente fornece os detalhes por telefone)
4. Define o novo cartão como padrão
5. Exclui o cartão vencido
6. Confirma com o cliente

Aviso

Nunca peça aos clientes para enviar detalhes do cartão por e-mail ou mensagem de texto. Sempre use:

• Portal seguro de Autoatendimento para autoatendimento
• Telefone com funcionários inserindo detalhes diretamente no sistema
• Pessoalmente em local de varejo

O Que Acontece Quando os Cartões Expiram

Quando um cartão de pagamento atinge sua data de vencimento e não é atualizado:

Efeitos Imediatos:

1. Pagamentos Automáticos Falham
   • O fornecedor de pagamento rejeita transações com cartões expirados
   • Renovações de serviços mensais falham ao processar
   • Recargas automáticas falham
   • Pagamentos automáticos de faturas falham
2. Notificações ao Cliente
   • O sistema tenta cobrar o cartão
   • Notificação de falha de pagamento enviada
   • E-mail "Atualizar Método de Pagamento" enviado com link para o portal de Autoatendimento
3. Mudanças no Status do Serviço
   • Serviços Pós-Pagos - Podem continuar temporariamente com saldo em aberto
   • Serviços Pré-Pagos - Suspensão do serviço quando o saldo se esgota
   • Serviços de Renovação Automática - Renovação falha, o serviço pode expirar

Ações Subsequentes:

Dia 1-3 (Período de Graça):

• O serviço continua normalmente
• O cliente recebe o primeiro aviso de falha de pagamento
• O sistema tenta uma nova tentativa (dependendo da configuração)

Dia 4-7:

• Segunda tentativa de pagamento (se configurado)
• E-mail de aviso enviado
• O atendimento ao cliente pode entrar em contato com o cliente

Dia 8-14:

• O serviço pode ser suspenso por falta de pagamento
• O status suspenso impede o uso, mas preserva a conta
• O cliente pode restaurar atualizando o método de pagamento e pagando o saldo em aberto

Dia 15+:

• O serviço pode ser encerrado por falta de pagamento
• Inventário (cartões SIM, equipamentos) marcado para devolução
• Último aviso enviado
• Conta encaminhada para cobrança (se aplicável)

Prevenindo Interrupção do Serviço:

Para evitar interrupção do serviço:

• Atualize os cartões 30 dias antes do vencimento
• Adicione múltiplos métodos de pagamento para redundância
• Ative alertas de falha de pagamento
• Monitore o painel de Cartões Vencendo semanalmente

Restaurando o Serviço Após o Vencimento:

Se o serviço foi suspenso devido a um cartão expirado:

1. Adicione um novo método de pagamento válido
2. Defina como padrão
3. Pague o saldo em aberto (se houver)
4. Entre em contato com o suporte para reativar o serviço
5. Serviço restaurado em minutos a horas

Segurança do Método de Pagamento

Tokenização

O OmniCRM usa tokenização do fornecedor para garantir segurança:

1. O cliente insere o cartão → Enviado diretamente aos servidores do fornecedor de pagamento
2. O fornecedor valida e tokeniza → Cria um token único
3. Token armazenado no OmniCRM → Número completo do cartão nunca é armazenado
4. Processamento de pagamento → Token enviado ao fornecedor, fornecedor cobra o cartão

O Que o OmniCRM Armazena:

{
  "vendor": "stripe",
  "vendor_payment_method_id": "pm_1A2B3C4D5E6F",
  "payment_type": "card",
  "brand": "visa",
  "last4": "1234",
  "exp_month": 12,
  "exp_year": 2026,
  "name": "John Smith",
  "nickname": "Personal Card",
  "is_default": true
}

O Que o OmniCRM NÃO Armazena:

• Número completo do cartão
• Código CVV/CVC
• Dados da faixa magnética
• Números PIN

Conformidade com PCI

Ao usar formulários de pagamento hospedados pelo fornecedor:

• Escopo PCI reduzido - Dados do cartão nunca tocam nos servidores do OmniCRM
• Campos hospedados pelo fornecedor - A entrada do cartão ocorre no iframe seguro do fornecedor
• Sem armazenamento de cartões - Tokens usados em vez de dados brutos do cartão
• Transmissão segura - Toda comunicação via HTTPS/TLS

Veja Payment System Guide <payment_system_guide> para detalhes de segurança do fornecedor de pagamento.

Fluxos de Trabalho Comuns

Fluxo de Trabalho 1: Cliente Adiciona Primeiro Método de Pagamento

Cenário: Novo cliente se inscrevendo para o serviço

1. O cliente cria uma conta
2. Seleciona o plano de serviço
3. Solicitado a adicionar um método de pagamento durante o checkout
4. Insere os detalhes do cartão no modal do Stripe
5. Cartão tokenizado e salvo
6. Automaticamente definido como padrão
7. Serviço provisionado
8. Primeiro pagamento processado

Fluxo de Trabalho 2: Cliente Atualiza Cartão Vencendo

Cenário: Cartão de crédito prestes a vencer

1. O cliente recebe notificação por e-mail (60 dias antes do vencimento)
2. Faz login no portal de Autoatendimento
3. Navega até Faturamento → Métodos de Pagamento
4. Revê o cartão atual que vence em 12/2025
5. Clica em "Adicionar Método de Pagamento"
6. Insere o cartão de substituição com vencimento 12/2028
7. Define o novo cartão como padrão
8. Exclui o cartão antigo
9. E-mail de confirmação enviado

Fluxo de Trabalho 3: Funcionário Ajuda Cliente por Telefone

Cenário: Cliente liga: "Meu cartão foi recusado"

1. O cliente liga para o suporte
2. O funcionário verifica a identidade (perguntas de segurança)
3. O funcionário verifica os métodos de pagamento: Cartão expirado 01/2025
4. Funcionário: "Seu cartão expirou. Você tem um novo cartão?"
5. O cliente fornece os novos detalhes do cartão por telefone
6. O funcionário navega até Clientes → [Cliente] → Faturamento
7. Clica em "Adicionar Método de Pagamento"
8. Insere os detalhes do cartão enquanto o cliente os lê
9. Define o novo cartão como padrão
10. Exclui o cartão expirado
11. Tenta o pagamento falhado novamente
12. Confirma com o cliente: "Pagamento bem-sucedido, serviço restaurado"

Fluxo de Trabalho 4: Cliente Empresarial com Múltiplos Cartões

Cenário: A empresa quer cartões diferentes para diferentes propósitos

1. O cliente empresarial adiciona o cartão principal (Visa terminando em 1111)
2. Define como padrão para cobranças mensais de serviços
3. Adiciona cartão de backup (Mastercard terminando em 2222) para recargas
4. Adiciona cartão de compras (Amex terminando em 3333) para compras de equipamentos
5. Ao fazer uma recarga, seleciona Mastercard manualmente no checkout
6. O Visa padrão ainda é usado para faturamento automático mensal

Fluxo de Trabalho 5: Gerenciando Cartões Vencendo (Admin)

Cenário: Gerenciamento proativo de vencimentos

1. O administrador navega até Faturamento → Cartões Vencendo
2. Filtros: "Próximos 30 dias"
3. Vê 15 clientes com cartões vencendo
4. Seleciona todos → "Enviar E-mails de Lembrete"
5. O Mailjet envia e-mails personalizados para cada cliente
6. Os clientes atualizam os cartões via Autoatendimento
7. O administrador revisa a lista 1 semana depois
8. Liga para os clientes restantes que não atualizaram
9. Auxilia com atualizações de cartões por telefone

Resolução de Problemas

"Cartão recusado" ao adicionar método de pagamento

• Causa: O fornecedor de pagamento rejeitou o cartão (fundos insuficientes, prevenção de fraude, recusa do emissor)
• Solução:
  • Tente um cartão diferente
  • Entre em contato com o emissor do cartão para autorizar a transação
  • Certifique-se de que o cartão suporta compras online
  • Verifique se o endereço de faturamento corresponde ao cartão registrado

"Erro ao adicionar método de pagamento" (erro genérico)

• Causa: Erro da API do fornecedor de pagamento ou problema de rede
• Solução:
  • Atualize a página e tente novamente
  • Verifique a conexão com a internet
  • Verifique se a configuração do fornecedor de pagamento está correta nas configurações do sistema
  • Verifique o console do navegador para mensagens de erro específicas
  • Tente um navegador diferente (desative bloqueadores de anúncios)

Não é possível excluir método de pagamento (botão desativado)

• Causa: Tentando excluir o cartão padrão, ou é o único cartão
• Solução:
  • Defina um cartão diferente como padrão primeiro
  • Se for o único cartão, adicione um novo cartão antes de excluir

Cartão aparece como expirado, mas não na lista de "Cartões Vencendo"

• Causa: O cartão expirou recentemente, cache não atualizado
• Solução:
  • Atualize a página
  • Verifique os filtros no painel de Cartões Vencendo
  • Cartões expirados podem se mover para uma visualização diferente

Novo cartão não aparece imediatamente

• Causa: A página não foi atualizada após a adição do cartão
• Solução:
  • A tabela de métodos de pagamento deve atualizar automaticamente
  • Se não, atualize manualmente o navegador
  • Verifique se ocorreu um erro durante o processo de adição

Modal de pagamento não carrega

• Causa: SDK do fornecedor de pagamento não carregando, problema com a chave da API ou extensão do navegador bloqueando
• Solução:
  • Verifique o console do navegador para erros
  • Desative bloqueadores de anúncios e proteção de rastreamento
  • Verifique a configuração do fornecedor de pagamento nas configurações do sistema
  • Certifique-se de que o script do SDK do fornecedor carrega (verifique a aba Rede)
  • Tente o modo de navegação anônima/privada

Cliente não recebe notificações de vencimento

• Causa: Mailjet não configurado ou modelo de e-mail ausente
• Solução:
  • Verifique as credenciais do Mailjet em crm_config.yaml
  • Verifique se o modelo de e-mail existe para vencimento do cartão
  • Confirme se o endereço de e-mail do cliente é válido
  • Verifique os logs do Mailjet para falhas de entrega

Melhores Práticas

Para Clientes:

• Adicione o método de pagamento antes da ativação do serviço para evitar atrasos
• Mantenha pelo menos 2 cartões registrados para redundância
• Atualize cartões que estão prestes a vencer com 30+ dias de antecedência
• Exclua cartões antigos/vencidos para evitar confusão
• Use nomes de usuário descritivos ("Visa Pessoal", "Amex de Trabalho")
• Verifique se o método de pagamento padrão está correto para faturamento automático

Para Funcionários de Suporte:

• Verifique a identidade do cliente antes de acessar os métodos de pagamento
• Nunca peça aos clientes para enviar detalhes do cartão por e-mail/SMS/chat
• Processe adições de cartões imediatamente durante as chamadas (não adie)
• Confirme se o novo cartão está definido como padrão após a adição
• Exclua cartões antigos apenas após confirmar que o novo cartão funciona
• Teste o pagamento após atualizar o cartão expirado (processo de autorização de £0,01)

Para Administradores:

• Monitore o painel de Cartões Vencendo semanalmente
• Envie e-mails de lembrete 60/30/7 dias antes do vencimento
• Mantenha as chaves de teste/produção do fornecedor de pagamento separadas para desenvolvimento vs produção
• Certifique-se de que os modelos do Mailjet estão configurados para notificações de vencimento
• Revise relatórios de falha de pagamento para identificar cartões expirados
• Treine a equipe sobre procedimentos seguros de manuseio de cartões

Documentação Relacionada

• Payment System Guide <payment_system_guide> - Referência completa da API de pagamento e arquitetura
• payments_process - Processamento de pagamentos com métodos de pagamento armazenados
• payments_invoices - Pagamento automático de faturas usando o cartão padrão
• features_topup_recharge - Sistema de recarga usando métodos de pagamento
• basics_payment - Conceitos gerais de pagamento e faturamento
• customer_care - Portal de Autoatendimento para clientes gerenciarem seus próprios cartões