Como integrar validação de CPF em checkout transparente (Stripe, Pagar.me)

Para integrar validação de CPF no checkout transparente do Stripe ou Pagar.me, faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key no backend antes de criar o Payment Intent ou a transação. A API da CPFHub.io retorna nome, data de nascimento e gênero do titular com latência média de ~900ms, permitindo verificar se o nome informado corresponde ao CPF antes de processar o pagamento. Essa camada de validação reduz chargebacks, melhora a taxa de aprovação nos gateways e garante dados consistentes para emissão de nota fiscal.

Por que validar CPF no checkout transparente

Redução de chargebacks

Chargebacks custam caro -- não apenas o valor da transação, mas também taxas adicionais cobradas pelas adquirentes. A validação de CPF no checkout cria uma camada que impede a maioria das tentativas de compra com dados roubados.

Melhoria na taxa de aprovação

Quando os dados enviados ao gateway são consistentes -- nome, CPF e dados do cartão pertencem à mesma pessoa -- a taxa de aprovação aumenta. Gateways utilizam essas informações para calcular o score de risco da transação.

Conformidade fiscal

A emissão de nota fiscal exige CPF válido do comprador. Validar o documento no checkout elimina problemas posteriores com notas fiscais rejeitadas ou com dados inconsistentes.

Dados de qualidade para analytics

Um cadastro de clientes com CPFs validados permite análises mais precisas -- taxa de recompra real, lifetime value por cliente e detecção de comportamentos anômalos.

Integração com Stripe

O Stripe não possui um campo nativo de CPF, mas permite enviar metadados customizados junto com cada transação. A estratégia é validar o CPF antes de criar o Payment Intent e incluir os dados validados como metadata. Consulte a documentação oficial do Stripe para detalhes sobre Payment Intents e campos de metadata.

Exemplo em Node.js com Stripe

const express = require("express");
const axios = require("axios");
const Stripe = require("stripe");

const stripe = Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();
app.use(express.json());

async function validarCpf(cpf) {
    try {
    const response = await axios.get(
    `https://api.cpfhub.io/cpf/${cpf}`,
    {
    headers: {
    "x-api-key": process.env.CPFHUB_API_KEY,
    Accept: "application/json",
    },
    timeout: 10000,
    }
    );
    return response.data;
    } catch (error) {
    console.error("Erro ao validar CPF:", error.message);
    return null;
    }
}

app.post("/api/create-payment-intent", async (req, res) => {
    const { cpf, nomeCliente, valor, email } = req.body;

    // 1. Validar CPF antes de criar Payment Intent
    const resultadoCpf = await validarCpf(cpf);

    if (!resultadoCpf || !resultadoCpf.success) {
    return res.status(400).json({
    error: "CPF inválido ou não encontrado",
    });
    }

    // 2. Verificar consistência do nome
    const nomeApi = resultadoCpf.data.nameUpper;
    const nomeInput = nomeCliente.toUpperCase().trim();

    if (nomeApi !== nomeInput) {
    return res.status(400).json({
    error: "O nome informado não corresponde ao CPF",
    });
    }

    // 3. Criar Payment Intent com metadata do CPF validado
    try {
    const paymentIntent = await stripe.paymentIntents.create({
    amount: valor, // em centavos
    currency: "brl",
    receipt_email: email,
    metadata: {
    cpf: resultadoCpf.data.cpf,
    cpf_nome_validado: resultadoCpf.data.nameUpper,
    cpf_validado_em: new Date().toISOString(),
    cpf_genero: resultadoCpf.data.gender,
    },
    });

    res.json({
    clientSecret: paymentIntent.client_secret,
    cpfValidado: true,
    });
    } catch (error) {
    console.error("Erro ao criar Payment Intent:", error.message);
    res.status(500).json({ error: "Erro ao processar pagamento" });
    }
});

app.listen(3000, () => console.log("Servidor rodando na porta 3000"));

Integração com Pagar.me

O Pagar.me já suporta o campo de CPF nativamente em transações brasileiras, o que facilita a integração. A validação via API da CPFHub.io adiciona a camada de verificação que o gateway não fornece por padrão.

Exemplo em Node.js com Pagar.me

const axios = require("axios");

async function criarTransacaoPagarme(dadosCompra) {
    const { cpf, nome, email, valor, cardHash } = dadosCompra;

    // 1. Validar CPF via CPFHub
    let dadosCpf;
    try {
    const cpfResponse = await axios.get(
    `https://api.cpfhub.io/cpf/${cpf}`,
    {
    headers: {
    "x-api-key": process.env.CPFHUB_API_KEY,
    Accept: "application/json",
    },
    timeout: 10000,
    }
    );
    dadosCpf = cpfResponse.data;
    } catch (error) {
    throw new Error("Falha na validação do CPF");
    }

    if (!dadosCpf.success) {
    throw new Error("CPF não encontrado");
    }

    // 2. Verificar nome
    if (dadosCpf.data.nameUpper !== nome.toUpperCase().trim()) {
    throw new Error("Nome não corresponde ao CPF informado");
    }

    // 3. Criar transação no Pagar.me
    const transacao = await axios.post(
    "https://api.pagar.me/core/v5/orders",
    {
    items: [
    {
    amount: valor,
    description: "Pedido",
    quantity: 1,
    },
    ],
    customer: {
    name: dadosCpf.data.name,
    email: email,
    document: cpf,
    document_type: "cpf",
    type: "individual",
    },
    payments: [
    {
    payment_method: "credit_card",
    credit_card: {
    card_token: cardHash,
    installments: 1,
    statement_descriptor: "MINHA LOJA",
    },
    },
    ],
    metadata: {
    cpf_validado: true,
    cpf_validado_em: new Date().toISOString(),
    },
    },
    {
    headers: {
    Authorization: `Basic ${Buffer.from(
    process.env.PAGARME_API_KEY + ":"
    ).toString("base64")}`,
    "Content-Type": "application/json",
    },
    timeout: 30000,
    }
    );

    return {
    sucesso: true,
    transacaoId: transacao.data.id,
    cpfValidado: true,
    };
}

Validação no frontend

Para uma experiência fluida, a validação de CPF pode ocorrer assim que o cliente preenche o campo, antes mesmo de ele clicar em "Pagar". Isso evita frustrações ao final do checkout.

Exemplo de chamada no frontend

// Chamada ao backend que valida o CPF
async function validarCpfNoFormulario(cpf, nome) {
    const response = await fetch("/api/validar-cpf", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ cpf, nome }),
    });

    const resultado = await response.json();

    if (!resultado.valido) {
    document.getElementById("cpf-erro").textContent =
    "Verifique o CPF informado";
    document.getElementById("btn-pagar").disabled = true;
    return false;
    }

    document.getElementById("cpf-erro").textContent = "";
    document.getElementById("btn-pagar").disabled = false;
    return true;
}

// Disparar validação ao sair do campo CPF
document.getElementById("cpf-input").addEventListener("blur", async (e) => {
    const cpf = e.target.value.replace(/\D/g, "");
    const nome = document.getElementById("nome-input").value;

    if (cpf.length === 11 && nome.length > 0) {
    await validarCpfNoFormulario(cpf, nome);
    }
});

Boas práticas de implementação

Nunca expor a API key no frontend

A chamada à API da CPFHub.io deve sempre ocorrer no backend. Expor a chave no código frontend permite que qualquer pessoa a utilize, consumindo suas consultas e comprometendo a segurança.

Implementar rate limiting

Mesmo no backend, limite o número de validações de CPF por sessão ou por IP para prevenir abuso. Duas ou três tentativas por sessão de checkout são suficientes para acomodar erros de digitação.

Cache de validações recentes

Se o mesmo cliente fizer múltiplas compras em curto período, não é necessário revalidar o CPF a cada transação. Um cache de 24 horas para CPFs já validados reduz o consumo de consultas.

Tratamento gracioso de erros

Se a API de CPF estiver temporariamente indisponível, o checkout não deve travar. Implemente um fallback que permita a compra com revisão manual posterior, garantindo que vendas legítimas não sejam perdidas.

Logging completo

Registre todas as validações de CPF -- tanto sucessos quanto falhas -- associadas à transação. Esses logs são valiosos para disputas de chargeback e para auditorias.

Impacto nas métricas de e-commerce

A validação de CPF no checkout transparente impacta positivamente diversas métricas:

• Taxa de chargeback: redução média de 40-60% com implementação adequada.
• Taxa de aprovação: aumento de 5-15%, pois dados consistentes elevam o score de confiança no gateway.
• Conversão: impacto neutro ou levemente positivo, já que a validação em tempo real é imperceptível para o cliente legítimo.
• Custo operacional: redução significativa em análise manual de pedidos suspeitos.

A API da CPFHub.io

Perguntas frequentes

Como a validação de CPF impede chargebacks no checkout transparente?

Ao verificar que o nome informado pelo comprador corresponde ao titular do CPF antes de criar o Payment Intent, você elimina a maioria das tentativas de compra com dados roubados. Um chargeback geralmente ocorre quando o verdadeiro titular do cartão não reconhece a compra — e a validação de CPF torna muito mais difícil que dados de terceiros passem pelo checkout.

A CPFHub.io bloqueia chamadas quando o limite mensal de consultas é atingido?

Não. A API não bloqueia nem retorna erro 429. Ao superar o limite do plano, cada consulta excedente é cobrada a R$0,15 automaticamente. O plano gratuito inclui 50 consultas/mês sem cartão de crédito; o plano Pro oferece 1.000 consultas por R$149/mês. Seu checkout nunca será interrompido por limite de uso da API.

Quanto tempo a validação de CPF adiciona ao fluxo de checkout?

A API da CPFHub.io opera com latência média de ~900ms. Como a validação ocorre no evento blur do campo CPF (quando o usuário sai do campo), ela acontece em paralelo enquanto o cliente preenche os dados do cartão — tornando o impacto percebido praticamente zero para o usuário.

Como garantir conformidade com a LGPD ao validar CPF no checkout?

Use o CPF apenas para a finalidade declarada (prevenção de fraude e emissão de nota fiscal), não persista o número em texto plano — armazene apenas um hash para reconciliação. Segundo a Autoridade Nacional de Proteção de Dados (ANPD), dados de identificação devem ser tratados com o princípio da necessidade. Documente a base legal para o tratamento e garanta que os logs de validação tenham controle de acesso restrito.

Conclusão

Integrar validação de CPF no checkout transparente com Stripe ou Pagar.me é uma decisão estratégica que protege o negócio, melhora a taxa de aprovação e fornece dados de qualidade para toda a operação. Com a API da CPFHub.io

Cadastre-se em cpfhub.io