Como Usar a API Stripe Identity: Guia do Desenvolvedor para Verificação de Identidade

Verificar a identidade de um usuário no mundo real parece simples, mas se transforma rapidamente em um projeto complexo: captura de documentos, OCR, reconhecimento facial, liveness, sinais de fraude e suporte a dezenas de documentos em vários países. A API Stripe Identity centraliza todas essas etapas em uma única integração, permitindo implementar um fluxo de verificação de identidade pronto para produção em poucas horas, não meses.

Experimente o Apidog hoje

Este guia mostra, passo a passo, como implementar o Stripe Identity: ativação no painel, criação de VerificationSession, escolha entre redirecionamento hospedado ou Stripe.js incorporado, tratamento de webhooks e leitura dos dados verificados. Traz exemplos em curl e Node, padrões de erro e dicas para testar tudo localmente com Apidog. Se ainda estiver avaliando alternativas, consulte também nosso comparativo das melhores APIs KYC.

O Stripe Identity é ideal para times que já usam Stripe para pagamentos, mas também opera de forma autônoma. A documentação do Stripe cobre o básico; aqui, detalhamos o que realmente importa para desenvolvedores: tráfego, campos, pontos críticos e como evitar erros comuns.

Em resumo

• O Stripe Identity valida usuários via documento oficial e selfie (liveness); preço inicia em US$ 1,50 por verificação nos EUA.
• O objeto central é o VerificationSession, criado no backend; depois, redirecione o usuário ou use Stripe.js.
• Solicite os campos necessários via options.document.require_matching_selfie, require_id_number e allowed_types.
• Monitore os webhooks identity.verification_session.verified e identity.verification_session.requires_input para atualizar o estado do app.
• Os outputs verificados (nome, data de nascimento, endereço, id) só aparecem se verified_outputs for definido na criação da sessão.
• Stripe Identity cobre mais de 35 países e aceita documentos localizados.

O que é a API Stripe Identity?

Stripe Identity é uma solução de verificação baseada na API Stripe, com endpoints do tipo /v1/identity/verification_sessions para captura de documentos, extração de dados, reconhecimento facial e score de fraude. O retorno é um registro assinado: nome completo, data de nascimento, endereço e opcionalmente número do documento, todos emparelhados às imagens originais armazenadas no Stripe.

O fluxo é baseado em sessões e webhooks, igual ao Checkout e Payment Intents: crie a sessão no backend, o Stripe cuida da interface de captura e você recebe notificações por webhook quando o resultado está pronto.

Autenticação e configuração

1. Ative o Stripe Identity no painel: Painel > Configurações > Identidade, aceite os termos e preencha os dados da empresa.
2. Use sua chave secreta do Stripe (sk_test_... para teste, sk_live_... para produção).

Instale o SDK Node:

npm install stripe

Inicialize o cliente e fixe a versão da API para evitar mudanças inesperadas:

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

Agora, utilize os métodos de stripe.identity.verificationSessions.

Endpoints principais

Criando uma VerificationSession

Crie um VerificationSession por tentativa de verificação. Configure tipos de documento aceitos, necessidade de selfie e campos a serem retornados.

Exemplo com curl:

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "$STRIPE_SECRET_KEY:" \
  -d "type=document" \
  -d "options[document][require_matching_selfie]=true" \
  -d "options[document][require_id_number]=true" \
  -d "options[document][allowed_types][]=driving_license" \
  -d "options[document][allowed_types][]=passport" \
  -d "verified_outputs[]=first_name" \
  -d "verified_outputs[]=last_name" \
  -d "verified_outputs[]=dob" \
  -d "verified_outputs[]=address" \
  -d "verified_outputs[]=id_number" \
  -d "metadata[user_id]=usr_7f3k2"

Exemplo com Node SDK:

const session = await stripe.identity.verificationSessions.create({
  type: "document",
  options: {
    document: {
      require_matching_selfie: true,
      require_id_number: true,
      allowed_types: ["driving_license", "passport", "id_card"],
    },
  },
  verified_outputs: [
    "first_name",
    "last_name",
    "dob",
    "address",
    "id_number",
  ],
  metadata: { user_id: "usr_7f3k2" },
});

// Envie para o cliente:
// session.url              -> redirecionamento hospedado
// session.client_secret    -> componente embutido Stripe.js

Dicas:

• type: "document" ativa a verificação de documento (padrão); id_number faz consultas de SSN (EUA).
• allowed_types restringe os documentos aceitos.
• verified_outputs define os campos retornados no output. Só dados solicitados são expostos.

Redirecionamento hospedado vs. Stripe.js incorporado

• Redirecionamento hospedado: envie o usuário para session.url (domínio stripe.com). Rápido de implementar, útil para etapas isoladas.
• Stripe.js incorporado: use o pacote @stripe/stripe-js e session.client_secret para montar o modal de verificação dentro do seu app. Ideal para onboarding integrado.

Webhooks

Não dependa do redirect do cliente. Sempre valide o status da verificação via webhook. No painel Stripe, registre um endpoint e assine os seguintes eventos:

• identity.verification_session.verified: verificação aprovada, dados disponíveis.
• identity.verification_session.requires_input: verificação falhou ou documento ilegível; permita nova tentativa.
• identity.verification_session.processing: status intermediário (útil para loading).
• identity.verification_session.canceled: sessão cancelada.

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers["stripe-signature"],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  if (event.type === "identity.verification_session.verified") {
    const session = event.data.object;
    await markUserVerified(session.metadata.user_id, session.id);
  }

  if (event.type === "identity.verification_session.requires_input") {
    await notifyUserToRetry(event.data.object.metadata.user_id);
  }

  res.json({ received: true });
});

Recuperando saídas verificadas

O webhook informa a aprovação, mas não envia dados sensíveis. Para obter os outputs, recupere a sessão expandindo verified_outputs:

const session = await stripe.identity.verificationSessions.retrieve(
  "vs_1N...",
  { expand: ["verified_outputs"] }
);

const { first_name, last_name, dob, address, id_number } = session.verified_outputs;

Observação:

• id_number é retornado apenas uma vez; armazene-o criptografado imediatamente.
• Imagens dos documentos ficam apenas no cofre Stripe, acessíveis pelo painel.

Erros comuns e limites de taxa

• Erros frequentes: verification_session.requires_input com códigos como document_unverified_other ou selfie_face_mismatch. Mostre uma opção para o usuário tentar novamente.
• Reutilize a mesma sessão (se aberta) ou cancele e crie nova.
• Limite de taxa: 100 req/s produção, 25 req/s teste. Ao exceder, HTTP 429 + header Retry-After; implemente recuo exponencial.
• Outros erros: unsupported_document_type (documento não aceito) e country_not_supported (país fora da cobertura Stripe).

Preços do Stripe Identity

• US$ 1,50 por verificação nos EUA. Demais países variam (Europa: US$ 1,50–2,00).
• Apenas sessões verified são cobradas; tentativas falhas (requires_input) não são faturadas.
• Grandes volumes (>10.000/mês) têm pricing negociado.

Testando o Stripe Identity com Apidog

Ferramentas de teste de API aceleram o desenvolvimento — especialmente para webhooks. O Apidog importa a OpenAPI do Stripe, exibe cada campo do VerificationSession e permite disparar requisições reais para o ambiente de teste do Stripe, inspecionando a resposta rapidamente.

No teste de webhook, o Apidog permite simular eventos como identity.verification_session.verified e enviá-los ao seu servidor local, facilitando o debug do handler sem precisar concluir uma verificação real. Veja também nosso guia sobre testes de API sem Postman. Baixe o Apidog para usar o cliente desktop.

Perguntas Frequentes

• Qual a diferença entre Stripe Identity e o KYC padrão do Stripe? O KYC padrão é interno ao Stripe para contas Connect. O Stripe Identity é uma API separada para verificar seus usuários finais. Os resultados não são compartilhados.
• Posso reutilizar uma identidade verificada? Sim, os verified_outputs de uma sessão verificada são permanentes para aquele objeto. Para novos eventos, crie uma nova sessão vinculada ao usuário.
• O Stripe Identity funciona fora de pagamentos? Sim. Muitas equipes utilizam apenas como camada KYC, sem usar pagamentos Stripe. Para triagem AML, combine com uma API de triagem AML dedicada.
• Como o Stripe Identity se compara ao Plaid Identity? Stripe foca em documento + selfie; Plaid em dados bancários. Veja nosso guia Plaid para detalhes.
• Liveness por selfie é obrigatório? Não. Defina options.document.require_matching_selfie como false para desativar. Equipes de fraude geralmente deixam ativado para maior segurança.
• Quais países são suportados? Mais de 35 países na América do Norte, Europa e Ásia-Pacífico, com analisadores de documentos localizados. A lista completa está na documentação do Stripe, que é atualizada regularmente.