Cobros y devoluciones masivos por el Portal Mercado Pago
La solución de cobros y devoluciones masivos por el Portal Mercado Pago te permite procesar un gran volumen de transacciones de tus clientes de forma segura, usando las tarjetas guardadas en la bóveda de Mercado Pago. El proceso se realiza mediante el envío de un archivo CSV a través de una interfaz visual del portal, sin necesidad de conocimientos técnicos avanzados.
Para realizar cobros o devoluciones masivas, accede primero a la interfaz a través del link provisto por tu contacto en Mercado Pago. Luego, sigue los pasos indicados a continuación.
Cobros masivos
A continuación se describe paso a paso cómo usar la solución de cobros masivos de tarjetas directamente en el portal del vendedor.
La base de todo el proceso es un archivo .csv que debe prepararse con los datos de los clientes y las tarjetas, siguiendo especificaciones estrictas. La precisión en este paso es fundamental para lograr éxito en los cobros.
csv
external_reference;card_id;payer_id;amount;reason;echo_data;soft_descriptor ref-4324_08_2026;3154;1234-1234;299;Ejemplo payment;dato random;CompanyName ref-4325_08_2026;3154;1234-1234;204;Ejemplo payment;dato random;CompanyName
Asegúrate de que tu archivo cumpla con las siguientes especificaciones y orden de datos:
| Orden | Encabezado | Descripción | Formato | Ejemplo | Tipo |
| 1 | external_reference | Identificador único del cobro en tu sistema. Sirve como clave de enlace entre el cobro en tu sistema y el pago generado por Mercado Pago, y es útil para la conciliación. | Máximo 64 caracteres. Solo números, letras, guiones (-) y guiones bajos (_). No se permiten caracteres especiales como [], (), '', @. | ref-4324_08_2026 | Obligatorio |
| 2 | card_id | Token de la tarjeta generado por Mercado Pago. | Caracteres alfanuméricos. | 1490022319978 | Obligatorio |
| 3 | payer_id | Token del customer/payer generado por Mercado Pago. | Caracteres alfanuméricos. | 123456789-jxOV430go9fx2e | Obligatorio |
| 4 | amount | Valor que será debitado del usuario pagador. | Valores numéricos positivos con separador decimal de coma. Ejemplo: 119,10 | — | Obligatorio |
| 5 | reason | Detalle o explicación del cobro. | Caracteres alfanuméricos. Máximo 255 caracteres. | Cobro de la suscripción | Opcional |
| 6 | echo_data | Campo de una sola dirección: se incluye en el archivo de entrada y se devuelve en el archivo de resultado para la conciliación inmediata. No se almacena junto al registro permanente del pago. | Caracteres alfanuméricos. Máximo 50 caracteres. | BATCH-012 | Opcional |
| 7 | soft_descriptor | Descripción del pago que se muestra en la factura del banco emisor de la tarjeta del cliente. | Caracteres alfanuméricos. Se recomienda un máximo de 25 caracteres. | Gimnasio-30081989 | Opcional |
Puntos clave a considerar:
-
Formato del archivo: el único formato aceptado es
.csv. -
Encabezado: completa la primera línea con los encabezados que aparecen en la tabla anterior.
-
Separación de datos: usa punto y coma (
;) para separar cada campo. -
Pertenencia: el
payer_idy elcard_iddeben corresponder a un cliente y una tarjeta vinculados a la cuenta del vendedor en Mercado Pago. -
Límites del archivo: el tamaño máximo es de 200.000 filas o 15 MB. Si tienes más filas, usa múltiples archivos.
-
Nombre del archivo: usa solo letras, números, guiones (
-), guiones bajos (_) y puntos (.).
Luego de preparar y revisar el archivo, debes cargarlo en la interfaz de Mercado Pago. Solo los usuarios con rol de Administrador en tu cuenta de Mercado Pago pueden realizar este paso. Si no tienes este permiso, contacta al administrador de tu cuenta para que haga el envío o actualice tu nivel de acceso a través de la sección Colaboradores.
Para eso, accede a la URL proporcionada por el equipo de soporte o tu representante de negocios de Mercado Pago y sigue los pasos a continuación.
1. Carga el archivo: en la interfaz "Gestiona tus pagos de forma masiva", selecciona o arrastra el archivo .csv al área indicada.
2. Confirma el envío: verifica que el nombre del archivo seleccionado sea el correcto y haz clic en "Procesar archivo" para iniciar el procesamiento de los cobros.
Mercado Pago aplica mecanismos automáticos para evitar el procesamiento de archivos duplicados:
- Nombre de archivo ya utilizado: se verifica si el nombre del archivo ya fue utilizado en un procesamiento anterior.
- Contenido duplicado: se impide el procesamiento de archivos cuyo contenido sea idéntico al de otro archivo ya procesado.
Aunque existen estos mecanismos automáticos, es tu responsabilidad revisar el nombre y el contenido del archivo antes de enviarlo para evitar cobros duplicados.
Después del envío, Mercado Pago ejecuta validaciones internas del archivo y da inicio al procesamiento de los pagos. A las 24 horas del envío ya es posible consultar el estado actualizado del procesamiento.
Para encontrar los resultados, accede a una de estas opciones:
- La pantalla principal de "Gestiona tus pagos de forma masiva", donde se muestra el último archivo enviado con su estado y la opción "Consultar histórico".
- La pantalla completa de "Histórico de archivos", accesible desde "Consultar histórico".
En "Histórico de archivos" encontrarás el nombre del archivo, el tipo (Cobros), el estado del procesamiento, la fecha de última actualización y la acción disponible según el estado.
El tipo de información disponible depende del estado del procesamiento:
| Estado | Acción | Observación |
| En proceso | Bajar vista previa | Aún hay cobros con resultado pendiente. Descarga el resultado parcial para seguir el avance del procesamiento. |
| Procesado | Bajar archivo final | El procesamiento finalizó correctamente. El archivo final con todos los resultados está disponible para descarga. |
| Error en el archivo | Ver motivos del error | Ningún cobro fue creado. El archivo contiene datos incorrectos y no habrá reporte para descargar. Prepara nuevamente el archivo respetando todos los campos obligatorios, el orden y formato indicados, y asegúrate de que no supere los 15 MB. |
Consulta las FAQs disponibles en la interfaz o contacta al Soporte de Mercado Pago si necesitas asistencia para identificar el motivo del error.
A continuación se muestra un ejemplo del contenido que encontrarás en el archivo de resultado:
csv
sequential_order;external_reference;amount;reason;echoData;payment_status;payment_detail;state_detail_code;payment_id;payment_date 1;2205353035;1000;"Cobro ejemplo 1";valido;Paid;accredited;E000;115629505401;"23/06/2025 15:58:36" 2;1827490885;2000;"Cobro ejemplo 2";valido;Paid;accredited;E000;115629505403;"23/06/2025 15:58:36" 3;2205353035;1000;"Cobro ejemplo 3";valido;Unpaid;"No fue posible procesar el pago.";E001;115629504412; 4;1827490885;2000;"Cobro ejemplo 4";valido;Unpaid;"El Customer ID o Card ID era inválido";E004;115629505414;
| Encabezado | Descripción | Formato | Ejemplo |
sequential_order | Orden del registro en relación al archivo de entrada. | Numérico. | 1 |
external_reference | Identificador único del cobro enviado en el archivo de entrada. | Alfanumérico. | ref-4324234332_08_2026 |
amount | Monto cobrado. | Numérico positivo con separadores decimales. | 199.10 |
reason | Detalle o explicación del cobro enviado en el archivo de entrada. | Alfanumérico. | Cobro de la suscripción |
echoData | Identificador de lote enviado en el archivo de entrada. | Alfanumérico. | BATCH-012 |
payment_status | Estado actual del pago. | Alfabético. | Paid |
payment_detail | Detalle del resultado del pago. | Alfanumérico. | accredited |
state_detail_code | Código del resultado basado en payment_detail. | Alfanumérico. | E000 |
payment_id | Identificador del pago generado por Mercado Pago. | Numérico. | 115629505401 |
payment_date | Fecha y hora de aprobación del pago. | Alfanumérico. | 23/06/2025 15:58:36 |
state_detail_code y payment_date se incluyen por defecto para todas las integraciones nuevas en Batch Payments iniciadas a partir de agosto de 2025. Si realizaste tu integración antes de esa fecha, solicita la inclusión de estas columnas contactando al Soporte de Mercado Pago o a tu representante de negocios.Los valores posibles de payment_status, payment_detail y state_detail_code son los siguientes:
payment_status | payment_detail | state_detail_code |
Processing | El cobro está en procesamiento. | E000 |
Paid | - accredited: El cobro fue ejecutado y el pago está aprobado.- partially_refunded: Existe un reembolso parcial ejecutado para este pago. | E000 |
Unpaid | El pago no fue aprobado: se intentó ejecutar el cobro, pero fue rechazado. | E001 |
Refunded | refunded: existe un reembolso total ejecutado para este pago. | E000 |
Invalid | No fue posible intentar ejecutar el pago por información inconsistente o que no cumple con las reglas. | E002: Email inválido.E003: Tarjeta vencida.E004: Customer ID o Card ID inválido.E005: External reference inválido.E006: Soft descriptor inválido.E008: Monto inválido.E101: Datos de tarjeta incompletos o inválidos.E102: Número de tarjeta inválido.E103: Datos sin el formato de separación correcto.E104: Esta columna no pudo procesarse.E105: Los datos en esta columna son obligatorios.E106: Los datos de la tarjeta no pudieron procesarse. |
Devoluciones masivas
A continuación se describe paso a paso cómo usar la solución de devoluciones masivas directamente en el portal del vendedor de Mercado Pago.
La base de todo el proceso es un archivo .csv que debe prepararse con los datos de las devoluciones, siguiendo especificaciones estrictas. La precisión en este paso es fundamental para lograr éxito en las devoluciones.
csv
payment_id;external_reference;amount 133008198979;ext_ref_1;100 142083165120;ext_ref_2;200
Asegúrate de que tu archivo cumpla con las siguientes especificaciones y orden de datos:
| Orden | Encabezado | Descripción | Formato | Ejemplo | Tipo |
| 1 | payment_id | Identificador del pago generado por Mercado Pago en la etapa de cobro. | Solo valores numéricos. | 133008198979 | Obligatorio |
| 2 | external_reference | Identificador único de la devolución en tu sistema. | Caracteres alfanuméricos, barras (/) y guiones (-, _). | ext_ref_1 | Obligatorio |
| 3 | amount | Valor que se devolverá al usuario pagador. | Valores numéricos positivos con separador decimal de coma. Ejemplo: 119,10 | — | Obligatorio |
Puntos clave a considerar:
-
Formato del archivo: el único formato aceptado es
.csv. -
Encabezado: completa la primera línea con los encabezados que aparecen en la tabla anterior.
-
Separación de datos: usa punto y coma (
;) para separar cada campo. -
Montos válidos: los valores deben ser positivos, conformes con la moneda del país y menores o iguales al valor de la transacción original.
-
Caracteres especiales: no se permiten caracteres especiales como
ñ,&,%,!,?ni similares. -
Nombre del archivo: usa solo letras, números, guiones (
-), guiones bajos (_) y puntos (.). -
Límites del archivo: el tamaño máximo es de 200.000 filas o 15 MB. Si tienes más filas, usa múltiples archivos.
Luego de preparar y revisar el archivo, debes cargarlo en la interfaz de Mercado Pago. Solo los usuarios con rol de Administrador en tu cuenta de Mercado Pago pueden realizar este paso. Si no tienes este permiso, contacta al administrador de tu cuenta para que haga el envío o actualice tu nivel de acceso a través de la sección Colaboradores.
Para eso, accede a la URL proporcionada por el equipo de soporte o tu representante de negocios de Mercado Pago y sigue los pasos a continuación.
1. Carga el archivo: en la interfaz "Gestiona tus pagos de forma masiva", selecciona o arrastra el archivo .csv de devolución al área indicada.
2. Confirma el envío: verifica que el nombre del archivo seleccionado sea el correcto y haz clic en "Procesar archivo" para iniciar el procesamiento de las devoluciones.
Mercado Pago aplica mecanismos automáticos para evitar el procesamiento de archivos duplicados:
- Nombre de archivo ya utilizado: se verifica si el nombre del archivo ya fue utilizado en un procesamiento anterior.
- Contenido duplicado: se impide el procesamiento de archivos cuyo contenido sea idéntico al de otro archivo ya procesado.
Aunque existen estos mecanismos automáticos, es tu responsabilidad revisar el nombre y el contenido del archivo antes de enviarlo para evitar devoluciones duplicadas.
Después del envío, Mercado Pago ejecuta validaciones internas del archivo y da inicio al procesamiento de las devoluciones. A las 24 horas del envío ya es posible consultar el estado actualizado del procesamiento.
Para encontrar los resultados, accede a una de estas opciones:
- La pantalla principal de "Gestiona tus pagos de forma masiva", donde se muestra el último archivo enviado con su estado y la opción "Consultar histórico".
- La pantalla completa de "Histórico de archivos", accesible desde "Consultar histórico".
En "Histórico de archivos" encontrarás el nombre del archivo, el tipo (Reembolso), el estado del procesamiento, la fecha de última actualización y la acción disponible según el estado.
El tipo de información disponible depende del estado del procesamiento:
| Estado | Acción | Observación |
| En proceso | Esperar la finalización | Aún hay devoluciones con resultado pendiente. Espera hasta que el procesamiento se complete para descargar el informe final. |
| Procesado | Bajar archivo final | El procesamiento finalizó correctamente. El archivo final con todos los resultados está disponible para descarga. |
| Error en el archivo | Ver motivos del error | Ninguna devolución fue creada. El archivo contiene datos incorrectos y no habrá reporte para descargar. Prepara nuevamente el archivo respetando todos los campos obligatorios, el orden y formato indicados, y asegúrate de que no supere los 15 MB. |
Consulta las FAQs disponibles en la interfaz o contacta al Soporte de Mercado Pago si necesitas asistencia para identificar el motivo del error.
A continuación se muestra un ejemplo del contenido que encontrarás en el archivo 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
| Encabezado | Descripción | Formato | Ejemplo |
sequential_order | Orden del registro en relación al archivo de entrada. | Numérico. | 1 |
external_reference | Identificador único de la devolución enviado en el archivo de entrada. | Alfanumérico. | ext_ref_1 |
amount | Valor del monto devuelto. | Numérico positivo con separadores decimales. | 199,10 |
refunds_status | Estado del reembolso. | Alfanumérico. Posibles valores: Refunded, Invalid, Rejected. | refunded |
refund_detail | Detalle del resultado del reembolso. | Alfabético. Posibles valores: refunded, El Payment ID ingresado es inválido, El monto ingresado es inválido, El external reference ingresado es inválido, No fue posible procesar el reembolso. | refunded |
payment_id | Identificador del pago generado por Mercado Pago. | Numérico. | 1885556854 |
Para más información o asistencia durante el proceso de devoluciones, contacta al soporte de Mercado Pago o a tu representante de negocios.