Como integrar validação de CPF em gateways de pagamento (PagSeguro, Mercado Pago)

Para integrar validação de CPF em gateways de pagamento como PagSeguro e Mercado Pago, chame a API do CPFHub.io no backend antes de enviar a transação ao gateway: valide os dígitos, confirme o nome do titular e compare com o nome informado no checkout. Se os dados coincidirem, prossiga com a transação já preenchida com os dados verificados — reduzindo chargebacks e problemas fiscais em até 90%.

Introdução

O Banco Central do Brasil regula o sistema financeiro nacional e define as normas que as instituições de pagamento e fintechs devem seguir.

Gateways de pagamento como PagSeguro, Mercado Pago, Stripe (com adaptações para o Brasil), Pagar.me e Cielo processam milhões de transações diárias no e-commerce brasileiro. Todos eles exigem o CPF do comprador como parte do processo de pagamento. No entanto, simplesmente coletar o CPF no formulário de checkout não garante que o número é válido ou que pertence ao comprador. Essa lacuna é explorada por fraudadores, resultando em chargebacks e prejuízos.

Por que validar CPF antes do gateway

Os gateways de pagamento validam se o CPF tem formato correto (11 dígitos, dígitos verificadores), mas não verificam se o CPF pertence ao comprador. Essa verificação de identidade é responsabilidade da loja.

Problemas de não validar

• Chargebacks -- Compras com CPF de terceiros geram contestações quando o titular descobre.

• Fraude com dados roubados -- Fraudadores usam CPFs válidos de outras pessoas.

• Problemas fiscais -- Notas fiscais emitidas com CPF incorreto podem ser rejeitadas.

• Bloqueio pelo gateway -- Taxas altas de chargeback podem levar ao bloqueio da conta no gateway.

Benefícios da validação prévia

• Redução de até 90% nos chargebacks.
• Notas fiscais emitidas com dados corretos.
• Menor índice de fraude reportado ao gateway.
• Melhor reputação junto às operadoras de cartão.

Arquitetura da integração

A validação de CPF deve acontecer entre a coleta dos dados do comprador e o envio da transação ao gateway.

Fluxo recomendado

1. Comprador preenche o formulário de checkout (CPF, nome, endereço, dados do cartão).
2. Antes de enviar ao gateway, o backend válida o CPF via API do CPFHub.io.
3. Se o CPF é válido e os dados conferem, a transação é enviada ao gateway.
4. Se o CPF não é encontrado ou os dados divergem, a compra é bloqueada ou encaminhada para revisão.

Exemplo com PagSeguro

O PagSeguro exige o CPF do comprador no objeto "sender" da transação. Antes de criar a transação, valide o CPF:

const express = require('express');
const app = express();
app.use(express.json());

async function validarCPF(cpf) {
    const cpfLimpo = cpf.replace(/\D/g, '');
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpfLimpo}`,
    {
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY,
    'Accept': 'application/json'
    },
    signal: AbortSignal.timeout(10000)
    }
    );
    return response.json();
}

app.post('/checkout/pagseguro', async (req, res) => {
    const { cpf, nome, email, valor, cartao } = req.body;

    // Passo 1: Validar CPF
    const validacao = await validarCPF(cpf);

    if (!validacao.success) {
    return res.status(400).json({
    erro: 'CPF não encontrado. Verifique os dados informados.'
    });
    }

    // Passo 2: Comparar nome
    const nomeCPF = validacao.data.nameUpper;
    const nomeInformado = nome.toUpperCase().trim();

    if (!nomeCPF.includes(nomeInformado.split(' ')[0])) {
    return res.status(400).json({
    erro: 'Nome informado não corresponde ao CPF.'
    });
    }

    // Passo 3: Enviar transação ao PagSeguro
    try {
    // Aqui entra a integração com a API do PagSeguro
    // usando os dados já validados
    const transacao = {
    sender: {
    name: validacao.data.name,
    cpf: validacao.data.cpf,
    email: email
    },
    amount: valor,
    // ... demais dados da transação
    };

    // const resultadoPagSeguro = await pagseguroAPI.createTransaction(transacao);

    return res.json({
    mensagem: 'Transação criada com sucesso',
    cpfValidado: true,
    titular: validacao.data.name
    });

    } catch (erro) {
    return res.status(500).json({
    erro: 'Falha ao processar pagamento'
    });
    }
});

app.listen(3000);

Exemplo com Mercado Pago

O Mercado Pago também requer CPF do pagador. A validação prévia segue o mesmo padrão:

import requests
import os

CPFHUB_API_KEY = os.environ.get("CPFHUB_API_KEY")
MERCADO_PAGO_TOKEN = os.environ.get("MERCADO_PAGO_TOKEN")

def validar_cpf(cpf):
    cpf_limpo = cpf.replace(".", "").replace("-", "")
    headers = {
    "x-api-key": CPFHUB_API_KEY,
    "Accept": "application/json"
    }
    response = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf_limpo}",
    headers=headers,
    timeout=10
    )
    return response.json()

def criar_pagamento_mercado_pago(cpf, nome, email, valor):
    # Passo 1: Validar CPF
    validacao = validar_cpf(cpf)

    if not validacao.get("success"):
    return {"erro": "CPF não encontrado"}

    dados_cpf = validacao["data"]

    # Passo 2: Comparar nome
    if dados_cpf["nameUpper"] != nome.upper().strip():
    return {"erro": "Nome divergente do CPF"}

    # Passo 3: Criar pagamento no Mercado Pago
    payload = {
    "transaction_amount": valor,
    "description": "Compra na loja",
    "payer": {
    "email": email,
    "first_name": dados_cpf["name"].split()[0],
    "last_name": " ".join(dados_cpf["name"].split()[1:]),
    "identification": {
    "type": "CPF",
    "number": dados_cpf["cpf"]
    }
    }
    }

    headers_mp = {
    "Authorization": f"Bearer {MERCADO_PAGO_TOKEN}",
    "Content-Type": "application/json"
    }

    # response_mp = requests.post(
    # "https://api.mercadopago.com/v1/payments",
    # json=payload,
    # headers=headers_mp,
    # timeout=30
    # )

    return {
    "mensagem": "Pagamento criado com sucesso",
    "cpf_validado": True,
    "titular": dados_cpf["name"]
    }

# Exemplo de uso
resultado = criar_pagamento_mercado_pago(
    cpf="123.456.789-00",
    nome="João da Silva",
    email="joao@email.com",
    valor=199.90
)
print(resultado)

Tabela de compatibilidade com gateways

Em todos os casos, a validação do CPFHub.io deve ser chamada antes de enviar os dados ao gateway.

Tratamento de cenários especiais

CPF não encontrado

Quando a API retorna que o CPF não foi encontrado, ofereça ao comprador a opção de revisar o número informado. Não bloqueie imediatamente -- pode ser um erro de digitação.

Nome divergente

Se o nome do CPF não corresponde ao nome informado, considere:

• Variações de nome (com/sem acentos, abreviações).
• Nome social diferente do nome civil.
• Apelidos ou nomes do meio omitidos.

Implemente uma comparação flexível, usando pelo menos o primeiro e último nome.

Cota de consultas atingida

O CPFHub.io não bloqueia requisições ao atingir o limite do plano — a API continua funcionando e cobra R$0,15 por consulta adicional. Monitore seu consumo em app.cpfhub.io/settings/billing para antecipar eventuais cobranças de excedente.

Timeout da API

Se a API não responde dentro do timeout configurado, permita que a transação prossiga (graceful degradation), mas registre o evento para análise posterior.

Impacto nos indicadores do gateway

O CPFHub.io se encaixa diretamente nesse fluxo de checkout, adicionando uma camada de verificação de identidade que complementa as validações nativas dos gateways e reduz de forma mensurável a taxa de chargeback da sua operação.

Planos recomendados por volume

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

Integrar validação de CPF antes de enviar transações a gateways de pagamento como PagSeguro e Mercado Pago é uma medida simples que gera impacto significativo na redução de chargebacks, fraudes e problemas fiscais. A API do CPFHub.io se encaixa naturalmente no fluxo de checkout, adicionando uma camada de verificação de identidade que complementa as validações nativas dos gateways. A integração pode ser feita em qualquer linguagem, com tempo de resposta que não impacta a experiência de compra.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e reduza os chargebacks na sua operação de e-commerce a partir de hoje.