# Como integrar validação de CPF em gateways de pagamento (PagSeguro, Mercado Pago) > Aprenda a integrar validação de CPF antes do checkout em PagSeguro, Mercado Pago e outros gateways, reduzindo chargebacks e fraudes. **Publicado:** 13/07/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-gateways-de-pagamento --- 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](https://www.bcb.gov.br) 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: ```javascript 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: ```python 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 | Gateway | Campo CPF | Onde integrar validação | | --- | --- | --- | | PagSeguro | sender.cpf | Antes de createTransaction | | Mercado Pago | payer.identification.number | Antes de criar payment | | Pagar.me | customer.document | Antes de criar transaction | | Cielo | Payment.CreditCard.Holder | Antes de criar sale | | Stripe (Brasil) | payment_method.billing_details | Antes de criar payment_intent | | Asaas | customer.cpfCnpj | Antes de criar customer | 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](https://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 | Indicador | Sem validação | Com validação de CPF | | --- | --- | --- | | Taxa de chargeback | 2-5% | Menos de 0,5% | | Aprovação de vendas | 70-80% | Acima de 90% | | Bloqueio por gateway | Risco alto | Risco baixo | | Multas de bandeira | Recorrentes | Raras | 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 | Volume de transações | Plano CPFHub.io | Preço | | --- | --- | --- | | Até 50/mês | Grátis | R$ 0 | | Até 1.000/mês | Pro | R$ 149/mês | | Acima de 1.000/mês | Corporativo | Sob consulta | --- ## 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](https://www.gov.br/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. ### Leia também - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf) --- ## 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](https://www.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.