Recursos para IA

Importar cartões no painel do Mercado Pago

A funcionalidade de importação de cartões permite que empresas que já possuem uma base de clientes e cartões armazenados migrem esses dados de forma segura para o Mercado Pago. Após concluir a migração, os pagamentos são processados pela plataforma do Mercado Pago sem interrupções para os clientes.

Esse processo cria cartões tokenizadosRepresentação segura dos dados de um cartão por meio de um identificador único (token) que substitui as informações sensíveis. O token permite processar pagamentos sem expor os dados reais do cartão. em massa a partir do envio de um arquivo criptografado contendo os dados dos cartões.

Para acessar a ferramenta de importação de cartões, você precisa entrar em contato previamente com seu representante de negócios do Mercado Pago. Ao finalizar essa etapa, você receberá uma URL para acessar a interface de envio do arquivo no painel do Mercado Pago.

Caso ocorra algum erro ou imprevisto durante a integração desta solução, entre em contato com seu representante de negócios.

Conceder acesso a colaboradores

Por padrão, o acesso ao portal de importação de cartões está restrito a usuários com perfil de administrador. Para permitir que outros colaboradores também possam usar esta funcionalidade, crie um perfil com a permissão correspondente e atribua-o aos colaboradores desejados.

Preparação do arquivo

Prepare um arquivo .csv especificando os dados de cada cliente e seus cartões. Inclua a primeira linha com os cabeçalhos e separe cada campo com vírgulas. Todos os campos são obrigatórios. O arquivo admite até 100.000 linhas; se você tiver mais cartões, divida as informações em múltiplos arquivos. O tempo médio de criação de tokens é de 60 minutos a cada 10.000 linhas. O nome do arquivo .csv deve conter apenas letras, números, hífens (-), underlines (_) e pontos (.). Consulte as especificações na seguinte tabela:

OrdemCabeçalhoDescriçãoFormatoExemplo
1external_referenceIdentificador único do cliente no seu sistema.AlfanuméricoORD-123456
2customer_emailEndereço de e-mail do titular.Alfanumérico. O nome de usuário no e-mail deve conter ao menos 2 caracteres.ej@email.com
3card_numberNúmero do cartão.Numérico, de 13 a 19 dígitos.1234567812345678
4expiration_monthMês de vencimento.Numérico, de 2 dígitos.01
5expiration_yearAno de vencimento.Numérico, de 2 dígitos.25
6cardholder_nameNome que aparece no cartão.Utilize somente letras sem acentos e espaços, evitando números e caracteres especiais, como . , ; : - _ / \ ' " & @ + ( ) ñ e ç.ATILIO GARCIA

A seguir, você encontrará um exemplo de arquivo .csv.

csv
external_reference,customer_email,card_number,expiration_month,expiration_year,cardholder_name
ORD-123456,ej@email.com,1234567812345678,01,25,PABLO SANCHEZ
CLI-789012,test_payer@example.com,5480832801033311,12,26,MARIA GONZALEZ
USR-345678,test_payer@example.com,4509953566233704,06,27,JOAO SILVA
REF-456789,test_payer@example.com,4012888888881881,03,28,CAROLINA PEREZ

Validações do arquivo

O campo cardholder_name deve conter somente letras sem acentos e espaços, evitando números e caracteres especiais, como . , ; : - _ / \ ' " & @ + ( ) ñ e ç.

Criptografia do arquivo

O arquivo .csv deve ser criptografado antes do envio. O formato esperado é PGPPretty Good Privacy: protocolo de criptografia que garante a confidencialidade e integridade dos dados por meio de criptografia de chave pública. com extensão .asc ou .enc.

Veja a seguir o processo de criptografia utilizando o GnuPG, um software gratuito de criptografia. Você pode utilizar outros métodos desde que o resultado esteja no formato PGP.


Envio do arquivo criptografado

  1. Acesse a URL fornecida pelo seu representante de negócios.
  2. Na interface de Geração de tokens, arraste ou selecione o arquivo criptografado (.asc ou .enc).

Tela de geração de tokens em lote

  1. Verifique se o nome do arquivo está correto e clique em Gerar Tokens.

Interface de upload de arquivo

O sistema exibirá o status "Gerando tokens...". A conclusão pode levar várias horas dependendo do tamanho do arquivo. Você pode monitorar o procedimento no campo Últimos resultados.

Seção de últimos resultados

Interpretação do arquivo de resultados

Após a conclusão do processamento, consulte o resultado no Painel do Mercado Pago. Apenas os casos processados completamente com sucesso ou de forma parcial geram um arquivo de resultados.

Localização dos resultados

  1. Consulte o status mais recente dos seus envios na seção Últimos resultados.
  2. Clique no link de download para obter um arquivo .csv com o detalhamento dos tokens gerados e os possíveis erros.

Status de processamento Histórico de resultados

Se você concluiu a criação de tokens mas ainda não processou cobranças na plataforma, entre em contato com seu representante de negócios para continuar com o processo de integração.

Resolução de erros

Se o processamento foi parcial, o arquivo de resultados incluirá os erros encontrados. Consulte a tabela a seguir para identificar e resolver cada tipo de erro.

Exemplo de arquivo de resultados

ErroDescriçãoResolução
Registro do cliente gerado incorretamenteErro ao criar o registro do cliente ou ao adicionar o cartão.Revise os dados do cliente e do cartão. Se o erro persistir, entre em contato com o com seu representante de negócios.
Erro ao vincular um cartãoNão foi possível determinar o método de pagamento.Revise os dados do cartão ou utilize outro cartão.
Token de cartão gerado incorretamenteForam inseridos dados de cartão incorretos.Revise o número do cartão e a data de vencimento.
Data de vencimento expiradaAs datas de vencimento inseridas correspondem a datas passadas.Verifique se as datas de vencimento são futuras.
Formato de e-mail inválidoO e-mail não está no formato permitido (exemplo@email.com).Corrija o formato do e-mail.
Sintaxe do e-mail inválidaO e-mail contém caracteres não permitidos.Revise os caracteres do e-mail
O cartão é inválidoOs dados registrados correspondem a um cartão inválido.Utilize outro cartão.

Erros frequentes no arquivo

Consulte os problemas mais comuns ao preparar o arquivo e como resolvê-los.

ProblemaExemplo inválidoComo corrigir
cardholder_name com caracteres não permitidosJOSE PEREZ S.A., MARÍA GÓMEZ, JOÃO SILVA, ANA-MARIA, CLIENTE & CIAUse somente letras sem acentos e espaços como, por exemplo, JOSE PEREZ, MARIA GOMEZ, JOAO SILVA.
Arquivo CSV mal exportadoToda a linha fica entre aspas ou é usado outro separadorExporte o arquivo como CSV separado por vírgulas e mantenha o header exato do template.
Linhas vaziasUma linha sem dados entre registrosRemova as linhas vazias antes de enviar o arquivo.
Cartão vencidoexpiration_month=01, expiration_year=24Envie somente cartões com data de vencimento futura.
card_number incorretoToken, card_id ou identificador interno em vez do PANEnvie o PAN plano do cartão, com 13 a 19 dígitos.
customer_email com formato inválidocliente@, cliente.com, cliente@@email.comUse um e-mail com formato padrão como, por exemplo, cliente@email.com.

Uma vez que você tenha identificado os erros, ajuste-os e carregue um novo arquivo apenas com os dados corrigidos para os registros que apresentaram problemas. Você pode realizar quantas importações forem necessárias.

Próximo
Adobe Commerce
Mercado Pago na sua loja

Navegação

IntegraçõesDocumentaçãoReferência APIBiblioteca SDK

Recursos e Comunidade

ChangelogStatus Mercado PagoRelatório de errosSuporteNotíciasNewsletterPrograma de parcerias

Mercado Pago

Sua contaTermos de usoPolíticas de privacidade

País e idioma

Argentina
Argentina
Brasil
México
Uruguay
Colombia
Chile
Perú
Português
Español
English
Português
Mercado Pago ofrece servicios de pago y no está autorizado por el Banco Central a operar como entidad financiera. Los fondos acreditados en cuentas de pago no constituyen depósitos en una entidad financiera ni están garantizados conforme legislación aplicable a depósitos en entidades financieras. Copyright © 2026 MercadoLibre S.R.L.

Usamos cookies para mejorar tu experiencia en Mercado Pago. Consultar más en nuestro Centro de Privacidad.

¡Listo! Guardamos tus preferencias.
Algo salió mal. Por favor, vuelve a intentarlo.