Blog

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

Ashley Innocent

Ashley Innocent

23 abril 2026

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

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

Verificar a identidade de um usuário no mundo real é uma daquelas tarefas que parecem simples no papel, mas se transformam em um projeto de meses no momento em que você começa a construí-lo. Você precisa de captura de documentos, OCR, reconhecimento facial, detecção de vida (liveness detection), sinais de fraude e cobertura para dezenas de tipos de documentos de identidade em diversos países. A API Stripe Identity empacota tudo isso em uma única integração, para que você possa implementar um fluxo de verificação de identidade pronto para produção em uma tarde, em vez de um trimestre.

Este guia descreve cada etapa que um desenvolvedor precisa para implementar o Stripe Identity: ativá-lo no painel, criar uma VerificationSession, escolher entre o redirecionamento hospedado e o componente Stripe.js incorporado, lidar com webhooks e ler as saídas verificadas. Você verá exemplos em curl e Node, padrões de tratamento de erros e como testar todo o fluxo localmente com Apidog. Se você estiver avaliando alternativas primeiro, dê uma olhada em nosso resumo das melhores APIs KYC antes de se comprometer.

botão

O Stripe Identity é uma solução natural para equipes que já usam o Stripe para pagamentos, mas também funciona como um produto autônomo. A documentação oficial do Stripe Identity cobre a superfície do produto, e esta publicação preenche as lacunas da experiência do desenvolvedor: o que acontece na rede, quais campos importam e onde estão os pontos de atenção comuns.

Em resumo

O que é a API Stripe Identity?

O Stripe Identity é um produto de verificação de identidade construído sobre a superfície da API principal do Stripe. Ele oferece uma única família de endpoints (/v1/identity/verification_sessions) que orquestra a captura de documentos, extração de dados, reconhecimento facial e pontuação de fraude. A saída é um registro assinado e estruturado em que você pode confiar: um nome completo verificado, data de nascimento, endereço e número de documento de identidade opcional, emparelhado com as imagens originais do documento armazenadas no cofre do Stripe.

Por debaixo dos panos, o Stripe usa o mesmo padrão de sessão mais webhook que você já conhece do Checkout e Payment Intents. Você cria uma sessão no lado do servidor, o Stripe lida com a interface de captura voltada para o usuário, e você é notificado quando o resultado está pronto. Se você já construiu um fluxo de Checkout antes, o Identity parecerá familiar em minutos.

Autenticação e configuração

Antes de chamar a API, ative o Stripe Identity no painel. Vá para Painel > Configurações > Identidade, aceite os termos e preencha os detalhes da empresa que o Stripe precisa para conformidade com KYC de sua parte. A alternância ativa o Identity para o modo de teste e modo ativo em sua conta.

A autenticação usa sua chave secreta padrão do Stripe. As chaves de teste começam com sk_test_ e as chaves ativas começam com sk_live_. O Stripe Identity não requer uma credencial separada, o que mantém a superfície de integração pequena.

Instale o SDK do Node:

npm install stripe

Em seguida, inicialize um cliente. Fixe a versão da API para que o Stripe nunca o surpreenda com uma mudança de esquema:

import Stripe from "stripe";

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

Agora você pode chamar todos os endpoints em stripe.identity.verificationSessions.

Endpoints principais

Criando uma VerificationSession

A VerificationSession é o único objeto que você cria por tentativa de verificação do usuário. Ela controla quais tipos de documentos são aceitos, se uma selfie é necessária e quais campos são retornados ao seu backend.

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"

Com o SDK do Node:

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" },
});

// Send one of these to the client:
// session.url              -> hosted redirect
// session.client_secret    -> Stripe.js embedded component

Alguns campos merecem atenção. type: "document" informa ao Stripe para executar uma verificação de documento; a alternativa, id_number, realiza uma consulta de estilo SSN (somente nos EUA) sem coletar um documento de identidade. allowed_types restringe quais categorias de documentos o usuário pode carregar, o que é importante para programas de conformidade que aceitam apenas documentos de identidade com foto emitidos pelo governo. verified_outputs é a lista de permissões dos campos que você deseja que sejam retornados; o Stripe não exporá nenhum dado que você não tenha solicitado, o que mantém sua postura de minimização de dados limpa.

Redirecionamento de verificação hospedado vs. Stripe.js incorporado

O Stripe oferece duas formas de integração. O redirecionamento hospedado é o caminho mais rápido: envie o usuário para session.url, o Stripe lida com toda a experiência de captura em um domínio stripe.com, e o usuário retorna para sua return_url. Você escreve aproximadamente dez linhas de código.

O fluxo incorporado usa Stripe.js e o pacote `@stripe/stripe-js` para montar um modal de verificação dentro do seu próprio aplicativo. Você passa session.client_secret para o frontend e chama stripe.verifyIdentity(clientSecret). Isso mantém os usuários em seu produto e lhe dá controle de design sobre a página circundante. Escolha-o quando a verificação ocorre no meio do fluxo em uma etapa de inscrição ou KYC; escolha o redirecionamento quando a verificação é uma tarefa discreta.

Webhooks

Nunca dependa do redirecionamento do cliente para informar que uma verificação foi bem-sucedida; sempre confirme no backend via webhooks. Registre um endpoint em Painel > Desenvolvedores > Webhooks e assine:

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 payload do webhook informa que a sessão foi verificada, mas não inclui os campos sensíveis. Para ler as saídas verificadas, chame verificationSessions.retrieve com expand: ["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;

O Stripe retorna o id_number apenas uma vez; armazene-o criptografado do seu lado imediatamente. As próprias imagens dos documentos permanecem no cofre do Stripe e são acessíveis através do painel para auditoria.

Erros comuns e limites de taxa

A falha mais frequente é verification_session.requires_input com um código como document_unverified_other ou selfie_face_mismatch. Lide com isso exibindo uma interface de usuário amigável para tentar novamente; a mesma sessão pode ser reutilizada chamando verificationSessions.cancel e criando uma nova, ou redirecionando para a mesma session.url enquanto ela ainda estiver aberta.

O Stripe aplica limites de taxa de API padrão de 100 requisições por segundo no modo ativo e 25 por segundo no modo de teste. Os endpoints `/identity/verification_sessions` se enquadram na mesma categoria que o restante da API. Se você atingir os limites, verá um HTTP 429 com um cabeçalho `Retry-After`; use o recuo exponencial e respeite o cabeçalho.

Outros erros a serem observados: unsupported_document_type quando o usuário carrega um documento de identidade fora da sua lista de allowed_types, e country_not_supported quando alguém tenta um documento de um dos países que o Stripe Identity ainda não cobre.

Preços do Stripe Identity

O Stripe Identity custa US$ 1,50 por verificação nos Estados Unidos. Os preços internacionais variam; a maioria dos países europeus fica em torno de US$ 1,50 a US$ 2,00, e o Stripe publica o detalhamento completo por país em sua página de preços. Uma tentativa de verificação que termina em requires_input não conta como um evento faturável; apenas as sessões verified concluídas são cobradas.

Para clientes com grande volume, o Stripe oferece preços personalizados que podem reduzir significativamente a taxa por verificação. Se você estiver processando mais de 10.000 verificações por mês, converse com a equipe de vendas.

Testando o Stripe Identity com Apidog

Ambientes de teste de API superam a criação manual de comandos curl em todos os momentos, especialmente ao iterar sobre payloads de webhook. O Apidog importa diretamente a especificação OpenAPI do Stripe, então cada campo no objeto VerificationSession aparece com documentação inline. Você pode disparar requisições reais para o ambiente de teste do Stripe, inspecionar a resposta e reproduzi-la quantas vezes precisar.

O lado do teste de webhook é onde o Apidog economiza mais tempo. Você pode simular eventos identity.verification_session.verified localmente, dispará-los para o seu servidor de desenvolvimento e depurar seu manipulador sem a necessidade de uma verificação real ser concluída. Se você estiver comparando fluxos de trabalho, nosso guia sobre teste de API sem Postman em 2026 oferece uma análise mais aprofundada. Baixe o Apidog para obter o cliente de desktop.

Perguntas Frequentes

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar