Verificacao de Identidade (Stripe)

O Levy Fleets se integra com o Stripe Identity para fornecer verificacao de identidade robusta para clientes. Isso ajuda a prevenir fraudes, cumprir regulamentacoes e garantir a seguranca dos usuarios. Este guia cobre modos de verificacao, gatilhos, o fluxo de verificacao e opcoes de gerenciamento.

Visao Geral

A verificacao de identidade confirma que um cliente e quem afirma ser, validando documentos de identificacao emitidos pelo governo. O sistema usa o Stripe Identity, que fornece:

• Escaneamento de documentos: Fotos de documentos de identidade (carteira de motorista, passaporte, RG)
• Correspondencia de selfie: Compara selfie com foto do documento
• Deteccao de vivacidade: Previne fraude com fotos
• Extracao de dados: Extrai nome verificado, data de nascimento, endereco do documento
• Pontuacao de risco: Integra-se com o Stripe Radar para deteccao de fraude

Modos de Verificacao

Cada subconta pode configurar um dos tres modos de verificacao:

Modo Desabilitado

identity_verification_mode: 'disabled'

• Nenhuma verificacao de identidade e necessaria
• Todos os clientes podem andar sem verificacao
• Util para ambientes de baixo risco ou lancamento inicial
• Sem custos de verificacao incorridos

Modo Todos os Usuarios

identity_verification_mode: 'all_users'

• Todo novo cliente deve verificar identidade antes da primeira viagem
• Verificacao solicitada durante o cadastro ou primeira tentativa de viagem
• Configuracao mais rigorosa para seguranca maxima
• Custos de verificacao mais altos, mas protecao maxima contra fraude

Modo Baseado em Risco

identity_verification_mode: 'risk_based'

• Verificacao necessaria apenas quando limite de risco e excedido
• Usa pontuacao de risco do Stripe Radar do primeiro pagamento
• Limite configuravel determina ponto de gatilho
• Equilibra seguranca com experiencia do cliente

Como Funciona a Verificacao Baseada em Risco

Calculo da Pontuacao de Risco

Quando um cliente faz seu primeiro pagamento, o Stripe Radar analisa:

• Caracteristicas do metodo de pagamento
• Endereco IP e localizacao
• Impressao digital do dispositivo
• Padroes historicos
• Pais emissor do cartao

O Stripe retorna um risk_level que o sistema converte em uma pontuacao:

Configuracao do Limite de Risco

As subcontas configuram uma pontuacao limite (padrao: 50):

identity_verification_risk_threshold: 50

Verificacao e necessaria quando: pontuacao_risco_cliente >= limite

Cenarios de Exemplo:

Quando a Pontuacao de Risco Ocorre

A pontuacao de risco e capturada durante a primeira cobranca bem-sucedida do cartao:

1. Cliente adiciona metodo de pagamento
2. Cliente inicia primeira viagem
3. No final da viagem, o pagamento e processado
4. Stripe Radar avalia a cobranca
5. Pontuacao de risco e armazenada no registro do cliente
6. Se o limite for excedido, a verificacao e sinalizada

Substituicao de Politica da Subconta

Algumas subcontas podem exigir verificacao para todos os usuarios independente do risco:

identity_verification_mode: 'all_users'

Quando isso e definido, a verificacao e necessaria antes da primeira viagem, ignorando a logica baseada em risco.

Fluxo de Verificacao

Experiencia do Cliente

1. Gatilho: Cliente tenta acao que requer verificacao
2. Notificacao: Notificacao push ou prompt no aplicativo aparece
3. Iniciar Stripe Identity: UI nativa de verificacao abre
4. Escaneamento de Documento: Cliente fotografa documento de identidade
5. Selfie: Cliente tira selfie para comparacao
6. Processamento: Stripe processa e verifica
7. Resultado: Resultado imediato de aprovado/reprovado exibido
8. Acesso a Viagem: Se aprovado, cliente pode prosseguir com viagens

Fluxo Tecnico

Acao do Cliente
    |
Verificar identity_verification_required
    |
Se necessario -> Chamada API para /api/customers/{id}/identity-session
    |
Sessao do Stripe Identity criada
    |
Client secret retornado para aplicativo movel
    |
SDK do Stripe Identity iniciado
    |
Verificacao concluida
    |
Webhook recebido: identity.verification_session.verified
    |
Registro do cliente atualizado com dados verificados
    |
identity_verification_required = false

Status de Verificacao

O status de identidade do cliente e rastreado no campo identity_status:

Indicadores no Painel

Banner de Verificacao de Identidade

Quando um cliente requer verificacao, um banner amarelo aparece na pagina de detalhes:

Conteudo do Banner:

• Titulo "Verificacao de Identidade Necessaria"
• Motivo do requisito (politica da subconta ou limite de risco)
• Data em que a verificacao foi sinalizada
• Pontuacao e nivel de risco atuais
• Status atual da verificacao
• Botao Remover Requisito

Secao de Verificacao de Identidade

A pagina de detalhes do cliente inclui uma secao dedicada mostrando:

Badges de Status

Os clientes podem exibir badges relacionados a verificacao:

Gerenciando Verificacao

Visualizando o Motivo do Requisito de Verificacao

Na pagina de detalhes do cliente, o banner de Verificacao de Identidade mostra por que a verificacao foi necessaria:

Politica da Subconta:

Motivo: Subconta requer verificacao para todos os usuarios

Limite de Risco Excedido:

Motivo: Pontuacao de risco 75 >= limite 50
Pontuacao de Risco: 75/100 (highest)

Removendo o Requisito de Verificacao

Para remover o requisito de verificacao sem que o cliente verifique:

1. Navegue ate a pagina de detalhes do cliente
2. Localize o banner amarelo de verificacao
3. Clique em Remover Requisito
4. Confirme a acao
5. O cliente agora pode andar sem verificar

Quando Usar:

• Cliente conhecido e confiavel incorretamente sinalizado
• Cliente verificou identidade por outros meios
• Decisao comercial de dispensar o requisito
• Avaliacao de risco estava incorreta

Verificacao Manual

Para marcar um cliente como verificado sem usar o Stripe Identity:

1. Navegue ate a pagina de detalhes do cliente
2. Na secao de Verificacao de Identidade, clique em Verificar Manualmente
3. Adicione observacoes explicando como a identidade foi confirmada
4. Confirme a acao

Quando Usar:

• Verificacao presencial em local fisico
• Cliente forneceu documentos de identidade por e-mail/suporte
• Migracao de cliente legado
• Verificacao via outro provedor de identidade

Campos de Banco de Dados de Verificacao Manual:

A verificacao manual ignora completamente o Stripe Identity. O identity_status do cliente e definido como verified e identity_verification_required e removido.

Solicitando Nova Verificacao

Para exigir que um cliente verifique novamente:

1. Navegue ate a pagina de detalhes do cliente
2. Clique em Acoes > Exigir Verificacao
3. Selecione um motivo
4. Confirme a acao

O cliente sera bloqueado de viagens ate completar a verificacao.

Dados Verificados

Quando um cliente verifica com sucesso, o Stripe Identity extrai:

Sempre Capturado

Quando Disponivel

Metadados de Verificacao

Notificacoes

O sistema envia notificacoes push para eventos relacionados a identidade:

Verificacao Necessaria

Quando a verificacao e sinalizada pela primeira vez:

• Titulo: "Verificacao de Identidade Necessaria"
• Corpo: "Por favor, verifique sua identidade para continuar usando o [Nome do App]"
• Tipo: identity
• Acao: Abre fluxo de verificacao no aplicativo

Verificacao Bem-sucedida

Apos verificacao bem-sucedida:

• Titulo: "Identidade Verificada"
• Corpo: "Sua identidade foi verificada. Voce esta pronto para andar!"
• Tipo: identity

Requisito Removido

Quando um operador remove o requisito:

• Titulo: "Tudo Certo!"
• Corpo: "Sua conta foi verificada e voce agora pode andar."
• Tipo: identity

Configuracao

Configuracoes da Subconta

Cada subconta configura as configuracoes de verificacao:

Configuracoes Recomendadas

Mercados de Alta Seguranca (regulados, ativos de alto valor):

mode: 'all_users'

Operacoes Padrao (abordagem equilibrada):

mode: 'risk_based'
threshold: 50

Mercados de Baixo Risco (comunidades confiaveis, ativos de baixo valor):

mode: 'disabled'

ou

mode: 'risk_based'
threshold: 75  # Apenas sinalizar maior risco

Dados de Risco de Consulta de Telefone

Alem do Stripe Radar, o sistema pode capturar dados de risco baseados em telefone:

Campos de Consulta de Telefone

Indicadores de Risco

Certas caracteristicas de telefone indicam risco maior:

• Numeros VOIP (Google Voice, etc.)
• Numeros portados recentemente
• Operadoras pre-pagas em certas regioes
• Incompatibilidade entre pais do telefone e local de cadastro

Rastreamento de Localizacao de Cadastro

O sistema rastreia onde os clientes se cadastraram para contexto adicional:

Localizacao Baseada em IP

Localizacao GPS

Indicadores de Risco de Localizacao

• Localizacao IP significativamente diferente do GPS
• Cadastro de VPN/proxy conhecido
• Localizacao longe de qualquer zona operacional

Referencia da API

Criar Sessao de Verificacao

Endpoint: POST /api/customers/{id}/identity-session

Resposta:

{
  "client_secret": "vs_client_secret_xxx",
  "session_id": "vs_xxx"
}

Obter Status de Identidade do Cliente

Endpoint: GET /api/customers/{id}

Retorna cliente com campos de identidade:

{
  "id": "...",
  "identity_verification_required": true,
  "identity_verification_required_at": "2024-01-15T10:30:00Z",
  "identity_verification_required_reason": "risk_threshold_exceeded:75>=50",
  "identity_status": "pending",
  "stripe_risk_score": 75,
  "stripe_risk_level": "highest"
}

Verificacao Manual

Endpoint: POST /api/customers/{id}/identity-manual-verify

Requisicao:

{
  "notes": "Verificado pessoalmente no local do centro"
}

Integracao com Sistema de Viagem

Verificacao de Verificacao no Inicio da Viagem

Quando um cliente tenta iniciar uma viagem (seja pelo aplicativo ou via painel "Iniciar Viagem"), o sistema verifica:

1. Verificacao e necessaria? -> Verificar flag identity_verification_required
2. Se necessaria, verificacao esta completa? -> Verificar identity_status === 'verified'
3. Bloquear viagem se nao verificado -> Retornar erro solicitando verificacao

Comportamento do Painel: Ao iniciar uma viagem pelo painel para um cliente que requer verificacao, a operacao falhara com uma mensagem de erro indicando que a verificacao e necessaria.

Comportamento do Aplicativo Movel: O aplicativo solicita que o cliente complete a verificacao antes de permitir o escaneamento da viagem.

Gatilhos Automaticos de Requisito de Verificacao

A verificacao pode ser automaticamente exigida quando:

1. Pontuacao de Risco do Primeiro Pagamento: Stripe Radar avalia a primeira cobranca
2. Limite de Risco Excedido: Pontuacao >= limite configurado
3. Politica da Subconta: Algumas subcontas exigem que todos os usuarios verifiquem

Impacto do Status de Verificacao nas Viagens

Melhores Praticas

Para Operadores

1. Escolha o modo apropriado: Combine o nivel de verificacao com sua tolerancia ao risco
2. Monitore clientes sinalizados: Nao deixe clientes presos no limbo de verificacao
3. Treine a equipe de suporte: Garanta que a equipe saiba lidar com problemas de verificacao
4. Documente verificacoes manuais: Sempre adicione observacoes ao ignorar o fluxo
5. Revise limites: Ajuste com base nas taxas reais de fraude

Para Suporte ao Cliente

1. Explique o requisito: Diga aos clientes por que a verificacao e necessaria
2. Oriente atraves do processo: Ajude com selecao de documento e dicas de foto
3. Escale apropriadamente: Verificar manualmente apenas quando justificado
4. Verifique antes de remover: Verifique se a remocao e apropriada para o caso

Para Equipes Tecnicas

1. Monitore entrega de webhook: Garanta que callbacks de verificacao estao sendo processados
2. Trate casos extremos: Considere cenarios de timeout e retry
3. Registre tentativas de verificacao: Mantenha trilha de auditoria
4. Teste regularmente: Verifique se o fluxo funciona em todos os ambientes

Solucao de Problemas

Cliente nao consegue completar verificacao

• Verifique se o Stripe Identity esta habilitado para sua conta Stripe
• Verifique se o aplicativo movel tem permissoes de camera
• Tente tipo diferente de documento de identidade
• Garanta iluminacao adequada para fotos do documento
• Verifique erros da API do Stripe nos logs

Verificacao passou mas cliente ainda bloqueado

• Verifique se identity_verification_required foi removido
• Verifique se o webhook foi processado corretamente
• Procure bloqueios adicionais (problema de pagamento, bloqueio manual)
• Verifique falhas de atualizacao do banco de dados

Pontuacao de risco parece incorreta

• Pontuacao de risco vem do Stripe Radar, nao controlada pelo Levy
• Revise a cobranca que acionou a pontuacao
• Verifique uso de VPN/proxy pelo cliente
• Considere ajuste de limite se consistentemente incorreto

Cliente verificou mas aparece como "pending"

• Verifique processamento de webhook para erros
• Atualize manualmente os dados do cliente do Stripe
• Verifique se o ID da sessao corresponde a verificacao atual
• Verifique sessoes sobrepostas multiplas