Cobranças e devoluções em massa pelo Portal Mercado Pago
A solução de cobranças e devoluções em massa pelo Portal Mercado Pago permite processar um grande volume de transações dos seus clientes com segurança, usando os cartões armazenados na bóveda do Mercado Pago. O processo é feito pelo envio de um arquivo CSV por meio de uma interface visual do portal, sem necessidade de conhecimentos técnicos avançados.
Para realizar cobranças ou devoluções em massa, acesse primeiro a interface através do link fornecido pelo seu contato no Mercado Pago. Em seguida, siga os passos indicados abaixo.
Cobranças em massa
A seguir está o passo a passo de como usar a solução de cobranças em massa de cartões diretamente no portal do vendedor.
A base de todo o processo é um arquivo .csv que deve ser preparado com os dados dos clientes e dos cartões, seguindo especificações rigorosas. A precisão nesta etapa é fundamental para obter sucesso nas cobranças.
csv
external_reference;card_id;payer_id;amount;reason;echo_data;soft_descriptor ref-4324_08_2026;3154;1234-1234;299;Exemplo payment;dado random;CompanyName ref-4325_08_2026;3154;1234-1234;204;Exemplo payment;dado random;CompanyName
Certifique-se de que o seu arquivo está de acordo com as seguintes especificações e ordem dos dados:
| Ordem | Cabeçalho | Descrição | Formato | Exemplo | Tipo |
| 1 | external_reference | Identificador único da cobrança no seu sistema. Serve como chave de ligação entre a cobrança no seu sistema e o pagamento gerado pelo Mercado Pago, sendo útil para a conciliação. | Máximo de 64 caracteres. Somente números, letras, hífens (-) e underscores (_). Não são permitidos caracteres especiais como [], (), '', @. | ref-4324_08_2026 | Obrigatório |
| 2 | card_id | Token do cartão gerado pelo Mercado Pago. | Caracteres alfanuméricos. | 1490022319978 | Obrigatório |
| 3 | payer_id | Token do customer/payer gerado pelo Mercado Pago. | Caracteres alfanuméricos. | 123456789-jxOV430go9fx2e | Obrigatório |
| 4 | amount | Valor que será debitado do usuário pagador. | Valores numéricos inteiros positivos, sem separadores decimais. Exemplo: 119 | — | Obrigatório |
| 5 | reason | Detalhe ou explicação da cobrança. | Caracteres alfanuméricos. Máximo de 255 caracteres. | Cobrança da assinatura | Opcional |
| 6 | echo_data | Campo de sentido único: é enviado no arquivo de entrada e devolvido no arquivo de resultado para conciliação imediata. Não fica armazenado junto ao registro permanente do pagamento. | Caracteres alfanuméricos. Máximo de 50 caracteres. | BATCH-012 | Opcional |
| 7 | soft_descriptor | Descrição do pagamento exibida na fatura do banco emissor do cartão do cliente. | Caracteres alfanuméricos. Recomenda-se no máximo 25 caracteres. | Academia-30081989 | Opcional |
Pontos importantes a considerar:
-
Formato do arquivo: o único formato aceito é
.csv. -
Cabeçalho: preencha a primeira linha com os cabeçalhos que aparecem na tabela acima.
-
Separação dos dados: use ponto e vírgula (
;) para separar cada campo. -
Pertencimento: o
payer_ide ocard_iddevem corresponder a um cliente e um cartão vinculados à conta do vendedor no Mercado Pago. -
Limites do arquivo: o tamanho máximo é de 200.000 linhas ou 15 MB. Se tiver mais linhas, use múltiplos arquivos.
-
Nome do arquivo: use apenas letras, números, hifens (
-), underscores (_) e pontos (.).
Com o arquivo preparado e revisado, carregue-o na interface do Mercado Pago. Somente usuários com o perfil de Administrador na sua conta do Mercado Pago podem realizar esta etapa. Se você não tiver esse privilégio, entre em contato com o administrador da sua conta para que ele faça o envio ou atualize o seu nível de acesso.
Acesse a URL fornecida pela equipe de suporte ou pelo seu representante de negócios do Mercado Pago ao formalizar o acesso.
1. Carregue o arquivo: na interface "Gestiona tus pagos de forma masiva", selecione ou arraste o arquivo .csv para a área indicada.
2. Confirme o envio: verifique se o nome do arquivo selecionado está correto e clique em "Procesar archivo" para iniciar o processamento das cobranças.
O Mercado Pago aplica mecanismos automáticos para evitar o processamento de arquivos duplicados:
- Nome de arquivo já utilizado: verifica-se se o nome do arquivo já foi utilizado em um processamento anterior.
- Conteúdo duplicado: impede-se o processamento de arquivos cujo conteúdo seja idêntico ao de outro arquivo já processado.
Embora existam esses mecanismos automáticos, é sua responsabilidade revisar o nome e o conteúdo do arquivo antes de enviá-lo para evitar cobranças duplicadas.
Após o envio, o Mercado Pago executa validações internas do arquivo e inicia o processamento dos pagamentos. 24 horas após o envio já é possível consultar o status atualizado do processamento.
Para encontrar os resultados, acesse uma destas opções:
- A tela principal de "Gestiona tus pagos de forma masiva", onde é exibido o último arquivo enviado com seu status e a opção "Consultar histórico", ou
- A tela completa de "Histórico de archivos", acessível a partir de "Consultar histórico".
Em "Histórico de archivos" você encontrará o nome do arquivo, o tipo (Cobros), o status do processamento, a data da última atualização e a ação disponível de acordo com o status.
O tipo de informação disponível depende do status do processamento:
| Status | Ação | Observação |
| Em processo | Baixar visualização prévia | Ainda há cobranças com resultado pendente. Faça o download do resultado parcial para acompanhar o andamento do processamento. |
| Processado | Baixar arquivo final | O processamento foi concluído com sucesso. O arquivo final com todos os resultados está disponível para download. |
| Erro no arquivo | Ver motivos do erro | Nenhuma cobrança foi criada. O arquivo contém dados incorretos e não haverá relatório para download. Prepare novamente o arquivo respeitando todos os campos obrigatórios, a ordem e o formato indicados, e certifique-se de que não supere 15 MB. |
Consulte as FAQs disponíveis na interface ou entre em contato com o suporte do Mercado Pago se precisar de ajuda para identificar o motivo do erro.
A seguir há um exemplo do conteúdo que você encontrará no arquivo de resultado:
csv
sequential_order;external_reference;amount;reason;echoData;payment_status;payment_detail;state_detail_code;payment_id;payment_date 1;2205353035;1000;"Cobrança exemplo 1";valido;Paid;accredited;E000;115629505401;"23/06/2025 15:58:36" 2;1827490885;2000;"Cobrança exemplo 2";valido;Paid;accredited;E000;115629505403;"23/06/2025 15:58:36" 3;2205353035;1000;"Cobrança exemplo 3";valido;Unpaid;"Não foi possível processar o pagamento.";E001;115629504412; 4;1827490885;2000;"Cobrança exemplo 4";valido;Unpaid;"O Customer ID ou Card ID era inválido";E004;115629505414;
| Cabeçalho | Descrição | Formato | Exemplo |
sequential_order | Ordem do registro em relação ao arquivo de entrada. | Numérico. | 1 |
external_reference | Identificador único da cobrança enviado no arquivo de entrada. | Alfanumérico. | ref-4324234332_08_2026 |
amount | Valor cobrado. | Numérico positivo com separadores decimais. | 199.10 |
reason | Detalhe ou explicação da cobrança enviado no arquivo de entrada. | Alfanumérico. | Cobrança da assinatura |
echoData | Identificador de lote enviado no arquivo de entrada. | Alfanumérico. | BATCH-012 |
payment_status | Status atual do pagamento. | Alfabético. | Paid |
payment_detail | Detalhe do resultado do pagamento. | Alfanumérico. | accredited |
state_detail_code | Código do resultado baseado no payment_detail. | Alfanumérico. | E000 |
payment_id | Identificador do pagamento gerado pelo Mercado Pago. | Numérico. | 115629505401 |
payment_date | Data e hora de aprovação do pagamento. | Alfanumérico. | 23/06/2025 15:58:36 |
state_detail_code e payment_date são incluídos por padrão em todas as novas integrações no Batch Payments iniciadas a partir de agosto de 2025. Se a sua integração for anterior a essa data, solicite a inclusão dessas colunas entrando em contato com o suporte do Mercado Pago ou com o seu representante de negócios.Os valores possíveis de payment_status, payment_detail e state_detail_code são os seguintes:
payment_status | payment_detail | state_detail_code |
Processing | A cobrança está em processamento. | E000 |
Paid | accredited — A cobrança foi executada e o pagamento está aprovado. partially_refunded — Existe um reembolso parcial executado para este pagamento. | E000 |
Unpaid | O pagamento não foi aprovado: tentou-se executar a cobrança, mas ela foi recusada. | E001 |
Refunded | refunded — Existe um reembolso total executado para este pagamento. | E000 |
Invalid | Não foi possível tentar executar o pagamento por informação inconsistente ou fora das regras. | E002 — E-mail inválido. E003 — Cartão vencido. E004 — Customer ID ou Card ID inválido. E005 — External reference inválido. E006 — Soft descriptor inválido. E008 — Valor inválido. E101 — Dados do cartão incompletos ou inválidos. E102 — Número do cartão inválido. E103 — Dados sem o formato de separação correto. E104 — Esta coluna não pôde ser processada. E105 — Os dados nesta coluna são obrigatórios. E106 — Os dados do cartão não puderam ser processados. |
Devoluções em massa
A seguir está o passo a passo de como usar a solução de devoluções em massa diretamente no portal do vendedor do Mercado Pago.
A base de todo o processo é um arquivo .csv que deve ser preparado com os dados das devoluções, seguindo especificações rigorosas. A precisão nesta etapa é fundamental para obter sucesso nas devoluções.
csv
payment_id;external_reference;amount 133008198979;ext_ref_1;100 142083165120;ext_ref_2;200
Certifique-se de que o seu arquivo está de acordo com as seguintes especificações e ordem dos dados:
| Ordem | Cabeçalho | Descrição | Formato | Exemplo | Tipo |
| 1 | payment_id | Identificador do pagamento gerado pelo Mercado Pago na etapa de cobrança. | Somente valores numéricos. | 133008198979 | Obrigatório |
| 2 | external_reference | Identificador único da devolução no seu sistema. | Caracteres alfanuméricos, barras (/) e hifens (-, _). | ext_ref_1 | Obrigatório |
| 3 | amount | Valor que será devolvido ao usuário pagador. | Valores numéricos inteiros positivos, sem separadores decimais. Exemplo: 119 | — | Obrigatório |
Pontos importantes a considerar:
-
Formato do arquivo: o único formato aceito é
.csv. -
Cabeçalho: preencha a primeira linha com os cabeçalhos que aparecem na tabela acima.
-
Separação dos dados: use ponto e vírgula (
;) para separar cada campo. -
Valores válidos: os valores devem ser positivos, estar em conformidade com a moeda do país e ser menores ou iguais ao valor da transação original.
-
Caracteres especiais: não são permitidos caracteres especiais como
ñ,&,%,!,?nem similares. -
Nome do arquivo: use apenas letras, números, hifens (
-), underscores (_) e pontos (.). -
Limites do arquivo: o tamanho máximo é de 200.000 linhas ou 15 MB. Se tiver mais linhas, use múltiplos arquivos.
Após preparar e revisar o arquivo, carregue-o na interface do Mercado Pago. Somente usuários com o perfil de Administrador na sua conta do Mercado Pago podem realizar esta etapa. Se você não tiver essa permissão, entre em contato com o administrador da sua conta para que ele faça o envio ou atualize o seu nível de acesso pela seção Colaboradores.
Para isso, acesse a URL fornecida pela equipe de suporte ou pelo seu representante de negócios do Mercado Pago e siga os passos abaixo.
1. Carregue o arquivo: na interface "Gestiona tus pagos de forma masiva", selecione ou arraste o arquivo .csv de devolução para a área indicada.
2. Confirme o envio: verifique se o nome do arquivo selecionado está correto e clique em "Procesar archivo" para iniciar o processamento das devoluções.
O Mercado Pago aplica mecanismos automáticos para evitar o processamento de arquivos duplicados:
- Nome de arquivo já utilizado: verifica-se se o nome do arquivo já foi utilizado em um processamento anterior.
- Conteúdo duplicado: impede-se o processamento de arquivos cujo conteúdo seja idêntico ao de outro arquivo já processado.
Embora existam esses mecanismos automáticos, é sua responsabilidade revisar o nome e o conteúdo do arquivo antes de enviá-lo para evitar devoluções duplicadas.
Após o envio, o Mercado Pago executa validações internas do arquivo e inicia o processamento das devoluções. 24 horas após o envio já é possível consultar o status atualizado do processamento.
Para encontrar os resultados, acesse uma destas opções:
- A tela principal de "Gestiona tus pagos de forma masiva", onde é exibido o último arquivo enviado com seu status e a opção "Consultar histórico", ou
- A tela completa de "Histórico de archivos", acessível a partir de "Consultar histórico".
Em "Histórico de archivos" você encontrará o nome do arquivo, o tipo (Reembolso), o status do processamento, a data da última atualização e a ação disponível de acordo com o status.
O tipo de informação disponível depende do status do processamento:
| Status | Ação | Observação |
| Em processo | Aguardar a finalização | Ainda há devoluções com resultado pendente. Aguarde até que o processamento seja concluído para fazer o download do relatório final. |
| Processado | Baixar arquivo final | O processamento foi concluído com sucesso. O arquivo final com todos os resultados está disponível para download. |
| Erro no arquivo | Ver motivos do erro | Nenhuma devolução foi criada. O arquivo contém dados incorretos e não haverá relatório para download. Prepare novamente o arquivo respeitando todos os campos obrigatórios, a ordem e o formato indicados, e certifique-se de que não supere 15 MB. |
Consulte as FAQs disponíveis na interface ou entre em contato com o suporte do Mercado Pago se precisar de ajuda para identificar o motivo do erro.
A seguir há um exemplo do conteúdo que você encontrará no arquivo de resultado:
csv
sequential_order;external_reference;amount;refunds_status;refund_detail;payment_id 1;ext_ref1;20398,00;refunded;refunded;1885556855 2;ext_ref2;10423,00;refunded;refunded;1885556854 3;ext_ref3;874,00;refunded;refunded;1885556853
| Cabeçalho | Descrição | Formato | Exemplo |
sequential_order | Ordem do registro em relação ao arquivo de entrada. | Numérico. | 1 |
external_reference | Identificador único da devolução enviado no arquivo de entrada. | Alfanumérico. | ext_ref_1 |
amount | Valor do montante devolvido. | Numérico positivo com separadores decimais. | 199,10 |
refunds_status | Status do reembolso. | Alfanumérico. Valores possíveis: Refunded, Invalid, Rejected. | refunded |
refund_detail | Detalhe do resultado do reembolso. | Alfabético. Valores possíveis: refunded, O Payment ID informado é inválido, O valor informado é inválido, O external reference informado é inválido, Não foi possível processar o reembolso. | refunded |
payment_id | Identificador do pagamento gerado pelo Mercado Pago. | Numérico. | 1885556854 |
Para mais informações ou assistência durante o processo de devoluções, entre em contato com o suporte do Mercado Pago ou com o seu representante de negócios.