Gerenciamento 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 integração com Stripe. Os métodos de pagamento possibilitam a cobrança automática por serviços, pagamentos únicos e cobranças recorrentes sem armazenar dados sensíveis do cartão no OmniCRM.

Veja também: Integração com Stripe, Visão Geral de Faturamento, Processamento de Pagamentos, Faturas.

Visão Geral

O sistema de métodos de pagamento fornece:

• Armazenamento Seguro de Cartões - Cartões tokenizados pelo Stripe, nunca armazenados no OmniCRM
• Múltiplos 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 Validade - Monitorar e atualizar cartões que estão prestes a expirar
• Autoatendimento - Clientes podem gerenciar seus próprios cartões através do Portal de Autoatendimento
• Gerenciamento de Funcionários - Funcionários de suporte podem adicionar/remover cartões em nome dos clientes

Métodos de Pagamento Suportados:

• 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)

Não Armazenado no OmniCRM:

Os detalhes do cartão são tokenizados pelo Stripe e armazenados de forma segura. O OmniCRM armazena apenas:

• Marca do cartão (Visa, Mastercard, etc.)
• Últimos 4 dígitos
• Mês/ano de validade
• Nome/nome de usuário do titular do cartão
• Referência do token do Stripe

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 que Estão Prestes a Expirar:

Visualize todos os clientes com cartões que estão prestes a expirar:

Isso mostra uma lista geral de cartões que expiram nos próximos 60 dias.

Lista de Métodos de Pagamento

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

{.align-center width="800px"}

Descrições das Colunas:

• Nome de Usuário - Nome amigável para o cartão (ex: "Cartão Pessoal", "Visa do Trabalho")
• Emissor - Marca do cartão e últimos 4 dígitos
• Validade - Mês/ano de expiração (formato MM/AAAA)
• 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 do Stripe.

Passo 1: Inserir Detalhes do Cartão

O modal de Stripe Elements aparece:

{.align-center width="800px"}

Campos Obrigatórios:

• Informações do Cartão - Número do cartão, validade, 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 do Stripe Elements:

• Detalhes do cartão inseridos diretamente no iframe seguro do Stripe
• O OmniCRM nunca vê ou armazena números completos de cartões
• Conformidade com PCI DSS gerenciada pelo Stripe
• Validação em tempo real evita números de cartão inválidos

Passo 2: Enviar e Tokenizar

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

1. Validação do Lado do Cliente:
   • O Stripe valida o formato do número do cartão
   • Verifica se a data de validade está no futuro
   • Verifica o formato do CVC
2. Tokenização:
   • Detalhes do cartão enviados diretamente para o Stripe (não para o OmniCRM)
   • O Stripe cria um token seguro (ex: pm_1A2B3C4D)
   • Token retornado ao OmniCRM
3. Processamento no Servidor:
   • O OmniCRM salva o token no registro do cliente
   • Armazena os últimos 4 dígitos, marca, validade para exibição
   • Nenhum número completo do cartão toca os 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 mudar o padrão após adicionar

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 recargas
• Transações únicas (a menos que especificado de outra forma)

Para Mudar o Padrão:

1. Localize o cartão que você 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:

Os 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 Validade: 12/2026

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

[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 Stripe.

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 que Estão Prestes a Expirar

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

Painel de Cartões que Estão Prestes a Expirar

Navegue até Faturamento → Cartões que Estão Prestes a Expirar para ver uma lista geral:

Cliente Cartão Validade 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 EXPIRADO Atualizar

Filtros:

• Intervalo de Validade - Próximos 30/60/90 dias ou já expirados
• Tipo de Cliente - Individual vs Empresa
• 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 Validade

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

• 60 dias antes da validade - Primeiro lembrete
• 30 dias antes da validade - Segundo lembrete
• 7 dias antes da validade - Aviso final
• Na validade - 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 validade
• 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 que Está Prestes a Expirar

Fluxo de Trabalho Recomendado:

1. O cliente recebe o e-mail de notificação de validade
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 validade atualizada ou cartão de substituição)
6. Define o novo cartão como padrão
7. Exclui o cartão antigo/expirado

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 expirado
6. Confirma com o cliente

::: warning ::: title Aviso :::

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

• Portal de Autoatendimento seguro 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 validade e não é atualizado:

Efeitos Imediatos:

1. Pagamentos Automáticos Falham
   • O Stripe rejeita transações com cartões expirados
   • Renovações mensais de serviços 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 pendente
   • Serviços Pré-pagos - Suspensão do serviço quando o saldo se esgota
   • Serviços de Renovação Automática - A 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 pendente

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 da validade
• Adicione múltiplos métodos de pagamento para redundância
• Habilite alertas de falha de pagamento
• Monitore o painel de Cartões que Estão Prestes a Expirar semanalmente

Restaurando o Serviço Após a Validade:

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

1. Adicione um novo método de pagamento válido
2. Defina como padrão
3. Pague o saldo pendente (se houver)
4. Contate 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 a tokenização do Stripe para garantir segurança:

1. Cliente insere o cartão → Enviado diretamente para os servidores do Stripe
2. Stripe 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 Stripe, Stripe cobra o cartão

O Que o OmniCRM Armazena:

{
  "customer_stripe_id": "pm_1A2B3C4D5E6F",
  "brand": "visa",
  "last4": "1234",
  "exp_month": 12,
  "exp_year": 2026,
  "name": "John Smith",
  "nickname": "Cartão Pessoal",
  "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 de PIN

Conformidade com PCI

Ao usar o Stripe Elements:

• Escopo PCI reduzido - Dados do cartão nunca tocam os servidores do OmniCRM
• Campos hospedados pelo Stripe - A entrada do cartão ocorre no iframe do Stripe
• 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 integrations_stripe para detalhes de segurança do Stripe.

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 um 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. Primeira cobrança processada

Fluxo de Trabalho 2: Cliente Atualiza Cartão que Está Prestes a Expirar

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

1. O cliente recebe notificação por e-mail (60 dias antes da validade)
2. Faz login no portal de Autoatendimento
3. Navega até Faturamento → Métodos de Pagamento
4. Revisão do cartão atual que expira em 12/2025
5. Clica em "Adicionar Método de Pagamento"
6. Insere cartão de substituição com validade 12/2028
7. Define novo cartão como padrão
8. Exclui 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 novo cartão como padrão
10. Exclui cartão expirado
11. Tenta novamente o pagamento falhado
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 que Estão Prestes a Expirar (Admin)

Cenário: Gerenciamento proativo de validade

1. O administrador navega até Faturamento → Cartões que Estão Prestes a Expirar
2. Filtros: "Próximos 30 dias"
3. Vê 15 clientes com cartões que estão prestes a expirar
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

Solução de Problemas

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

• Causa: O Stripe rejeitou o cartão (fundos insuficientes, prevenção de fraudes, recusa do emissor)
• Solução:
  • Tente um cartão diferente
  • Contate o emissor do cartão para autorizar a transação
  • Verifique se o cartão suporta compras online
  • Verifique se o endereço de cobrança corresponde ao cartão registrado

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

• Causa: Erro da API do Stripe ou problema de rede
• Solução:
  • Atualize a página e tente novamente
  • Verifique a conexão com a internet
  • Verifique se a chave publicável do Stripe está correta em .env
  • 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: Tentativa de 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 "Cartões que Estão Prestes a Expirar"

• Causa: Cartão expirou recentemente, cache não atualizado
• Solução:
  • Atualize a página
  • Verifique os filtros no painel de Cartões que Estão Prestes a Expirar
  • 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 do Stripe não carrega

• Causa: Biblioteca Stripe.js 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 contra rastreamento
  • Verifique REACT_APP_STRIPE_PUBLISHABLE_KEY em .env
  • Certifique-se de que o script Stripe.js carrega (verifique a aba de Rede)
  • Tente o modo de navegação anônima/privada

Cliente não recebe notificações de validade

• 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 validade 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 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 expirar com 30+ dias de antecedência
• Exclua cartões antigos/expirados para evitar confusão
• Use nomes de usuário descritivos ("Visa Pessoal", "Amex do Trabalho")
• Verifique se o método de pagamento padrão está correto para cobrança automática

Para Funcionários de Suporte:

• Verifique a identidade do cliente antes de acessar 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 (processar autorização de £0.01)

Para Administradores:

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

Melhores Práticas de Segurança:

• Use apenas chaves publicáveis do Stripe (nunca chaves secretas no frontend)
• Certifique-se de que todas as páginas de pagamento carreguem via HTTPS
• Revise regularmente o painel do Stripe em busca de atividades suspeitas
• Ative regras de prevenção de fraudes do Stripe
• Exija CVC para todas as transações sem cartão presente
• Registre mudanças de métodos de pagamento no log de atividades

Documentação Relacionada

• integrations_stripe - Configuração e configuração da integração com Stripe
• 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