# MD for: https://www.mercadopago.com.mx/developers/pt/docs/batch-payments/massive-charge-and-refund-portal.md

\# Bulk charges and refunds through the Mercado Pago Portal The \*\*bulk charges and refunds solution through the Mercado Pago Portal\*\* allows you to securely process large volumes of customer transactions using cards stored in the Mercado Pago vault. The process is carried out by uploading a CSV file through a visual portal interface, with no advanced technical knowledge required. > NOTE > > In addition to this solution, Mercado Pago also offers bulk charges and refunds via file upload through an SFTP interface. If using an SFTP interface is essential for your recurrence-based payment flow, contact Mercado Pago support or your business representative directly. To process bulk charges or refunds, first access the interface through the link provided by your Mercado Pago contact. Then, follow the steps indicated below. ## Bulk charges The following describes step by step how to use the bulk card charges solution directly in the seller portal. :::AccordionComponent{title="Prepare the charge file" pill="1"} The foundation of the entire process is a \*\*CSV file\*\* that must be prepared with customer and card data, following strict specifications. Accuracy in this step is essential for successful charges. \`\`\`csv external\_reference;card\_id;payer\_id;amount;reason;echo\_data;soft\_descriptor ref-4324\_08\_2026;3154;1234-1234;299;Example payment;random data;CompanyName ref-4325\_08\_2026;3154;1234-1234;204;Example payment;random data;CompanyName \`\`\` Make sure your file complies with the following \*\*specifications and data order\*\*: | Order | Header | Description | Format | Example | Type | |:---:|---|---|---|---|---| | \*\*1\*\* | \`external\_reference\` | Unique identifier of the charge in your system. Serves as a link between the charge in your system and the payment generated by Mercado Pago, and is useful for reconciliation. | Maximum 64 characters. Only numbers, letters, hyphens (\`-\`), and underscores (\`\_\`). Special characters such as \`\[\]\`, \`()\`, \`''\`, \`@\` are not allowed. | \`ref-4324\_08\_2026\` | Required | | \*\*2\*\* | \`card\_id\` | Card token generated by Mercado Pago. | Alphanumeric characters. | \`1490022319978\` | Required | | \*\*3\*\* | \`payer\_id\` | Customer/payer token generated by Mercado Pago. | Alphanumeric characters. | \`123456789-jxOV430go9fx2e\` | Required | | \*\*4\*\* | \`amount\` | Value to be debited from the paying user. | Positive numeric values with a period as the decimal separator. Example: \`119.10\` | — | Required | | \*\*5\*\* | \`reason\` | Detail or explanation of the charge. | Alphanumeric characters. Maximum 255 characters. | \`Subscription charge\` | Optional | | \*\*6\*\* | \`echo\_data\` | One-way field: it is sent in the input file and returned in the result file for immediate reconciliation. It is not stored alongside the permanent payment record. | Alphanumeric characters. Maximum 50 characters. | \`BATCH-012\` | Optional | | \*\*7\*\* | \`soft\_descriptor\` | Payment description shown on the statement of the card issuer's customer. | Alphanumeric characters. A maximum of 25 characters is recommended. | \`Gym-30081989\` | Optional | \*\*Key points to consider:\*\* - \*\*File format:\*\* the only accepted format is \`.csv\`. - \*\*Header row:\*\* fill in the first line with the headers shown in the table above. - \*\*Data separation:\*\* use a semicolon (\`;\`) to separate each field. - \*\*Ownership:\*\* the \`payer\_id\` and \`card\_id\` must correspond to a customer and a card linked to the seller's account in Mercado Pago. - \*\*File limits:\*\* the maximum size is 200,000 rows or 15 MB. If you have more rows, use multiple files. - \*\*File name:\*\* use only letters, numbers, hyphens (\`-\`), underscores (\`\_\`), and periods (\`.\`). ::: :::AccordionComponent{title="Upload the charge file" pill="2"} With the file prepared and reviewed, upload it to the Mercado Pago interface. Only users with the \*\*Administrator\*\* role in your Mercado Pago account can perform this step. If you do not have this privilege, contact your account administrator to make the upload or update your access level. Access the URL provided by the Mercado Pago support team or your business representative when \[formalizing access\](#bookmark\_formalize\_access\_to\_the\_interface). \*\*1\. Upload the file:\*\* in the "Gestiona tus pagos de forma masiva" interface, select or drag the \`.csv\` file to the indicated area. !\[File upload area in the Mercado Pago Portal\](https://www.mercadopago.com.mx/images/batch-payments/portal-upload-interface-es-v1.png) \*\*2\. Confirm the submission:\*\* verify that the selected file name is correct and click \*\*"Procesar archivo"\*\* to start processing the charges. !\[File selected and ready to process\](https://www.mercadopago.com.mx/images/batch-payments/portal-file-selected-es-v1.png) Mercado Pago applies automatic mechanisms to prevent duplicate file processing: - \*\*File name already used:\*\* it is verified whether the file name was already used in a previous processing. - \*\*Duplicate content:\*\* processing is blocked for files whose content is identical to another previously processed file. Although these automatic mechanisms exist, it is your responsibility to review the file name and content before uploading to avoid duplicate charges. ::: :::AccordionComponent{title="Track charge processing" pill="3"} After the upload, Mercado Pago runs internal file validations and starts processing the payments. \*\*24 hours after the upload\*\*, you can already check the updated processing status. > NOTE > > The processing time for all payments depends on various factors, most of which are outside Mercado Pago's control. In most cases, charges obtain a final result within 5 calendar days of the batch upload. To find the results, access one of these options: - The main screen of \*\*"Gestiona tus pagos de forma masiva"\*\*, which shows the last uploaded file with its status and the "Consultar histórico" option, or - The full \*\*"Histórico de archivos"\*\* screen, accessible from "Consultar histórico". !\[Main bulk charge tracking screen\](https://www.mercadopago.com.mx/images/batch-payments/portal-tracking-main-es-v1.png) In "Histórico de archivos" you will find the file name, type (Cobros), processing status, last update date, and the available action based on the status. !\[File history with processing statuses\](https://www.mercadopago.com.mx/images/batch-payments/portal-history-table-es-v1.png) The type of information available depends on the processing status: | Status | Action | Note | |:---:|:---:|---| | In process | Download preview | There are still charges with a pending final result. Download the partial result to track processing progress. | | Processed | Download final file | Processing completed successfully. The final file with all results is available for download. | | File error | View error reasons | No charges were created. The file contains incorrect data and there will be no report to download. Prepare the file again, making sure all required fields are included, the correct order and format are followed, and the file does not exceed 15 MB. | > WARNING > > Only the "In process" and "Processed" statuses generate a result file. If an error occurs during processing, there will be no file available for download. Check the FAQs available in the interface or contact Mercado Pago support if you need help identifying the cause of the error. ::: :::AccordionComponent{title="Interpret the charge result file" pill="4"} Below is an example of the content you will find in the result file: \`\`\`csv sequential\_order;external\_reference;amount;reason;echoData;payment\_status;payment\_detail;state\_detail\_code;payment\_id;payment\_date 1;2205353035;1000;"Charge example 1";valid;Paid;accredited;E000;115629505401;"23/06/2025 15:58:36" 2;1827490885;2000;"Charge example 2";valid;Paid;accredited;E000;115629505403;"23/06/2025 15:58:36" 3;2205353035;1000;"Charge example 3";valid;Unpaid;"Payment could not be processed.";E001;115629504412; 4;1827490885;2000;"Charge example 4";valid;Unpaid;"Customer ID or Card ID was invalid";E004;115629505414; \`\`\` | Header | Description | Format | Example | |---|---|---|---| | \`sequential\_order\` | Record order relative to the input file. | Numeric. | \`1\` | | \`external\_reference\` | Unique charge identifier sent in the input file. | Alphanumeric. | \`ref-4324234332\_08\_2026\` | | \`amount\` | Amount charged. | Positive numeric with decimal separators. | \`199.10\` | | \`reason\` | Detail or explanation of the charge sent in the input file. | Alphanumeric. | \`Subscription charge\` | | \`echoData\` | Batch identifier sent in the input file. | Alphanumeric. | \`BATCH-012\` | | \`payment\_status\` | Current payment status. | Alphabetic. | \`Paid\` | | \`payment\_detail\` | Payment result detail. | Alphanumeric. | \`accredited\` | | \`state\_detail\_code\` | Result code based on \`payment\_detail\`. | Alphanumeric. | \`E000\` | | \`payment\_id\` | Payment identifier generated by Mercado Pago. | Numeric. | \`115629505401\` | | \`payment\_date\` | Payment approval date and time. | Alphanumeric. | \`23/06/2025 15:58:36\` | > NOTE > > The \`state\_detail\_code\` and \`payment\_date\` fields are included by default for all new Batch Payments integrations started after August 2025\. If your integration predates that date, request the inclusion of these columns by contacting Mercado Pago support or your business representative. The possible values for \`payment\_status\`, \`payment\_detail\`, and \`state\_detail\_code\` are as follows: | \`payment\_status\` | \`payment\_detail\` | \`state\_detail\_code\` | |---|---|---| | \`Processing\` | The charge is being processed. | \`E000\` | | \`Paid\` | \`accredited\` — The charge was executed and the payment is approved. \`partially\_refunded\` — A partial refund was successfully executed for this payment. | \`E000\` | | \`Unpaid\` | The payment was not approved: a charge attempt was made but it was rejected. | \`E001\` | | \`Refunded\` | \`refunded\` — A full refund was successfully executed for this payment. | \`E000\` | | \`Invalid\` | It was not possible to attempt the payment due to inconsistent information or non-compliance with rules. | \`E002\` — Invalid email. \`E003\` — Expired card. \`E004\` — Invalid Customer ID or Card ID. \`E005\` — Invalid external reference. \`E006\` — Invalid soft descriptor. \`E008\` — Invalid amount. \`E101\` — Incomplete or invalid card data. \`E102\` — Invalid card number. \`E103\` — Data not in the correct separation format. \`E104\` — This column could not be processed. \`E105\` — Data in this column is required. \`E106\` — Card data could not be processed. | ::: ## Bulk refunds The following describes step by step how to use the bulk refunds solution directly in the Mercado Pago seller portal. :::AccordionComponent{title="Prepare the refund file" pill="1"} The foundation of the entire process is a \*\*CSV file\*\* that must be prepared with refund data, following strict specifications. Accuracy in this step is essential for successful refunds. \`\`\`csv payment\_id;external\_reference;amount 133008198979;ext\_ref\_1;100 142083165120;ext\_ref\_2;200 \`\`\` Make sure your file complies with the following \*\*specifications and data order\*\*: | Order | Header | Description | Format | Example | Type | |:---:|---|---|---|---|---| | \*\*1\*\* | \`payment\_id\` | Payment identifier generated by Mercado Pago at the charge stage. | Numeric values only. | \`133008198979\` | Required | | \*\*2\*\* | \`external\_reference\` | Unique refund identifier in your system. | Alphanumeric characters, slashes (\`/\`), and hyphens (\`-\`, \`\_\`). | \`ext\_ref\_1\` | Required | | \*\*3\*\* | \`amount\` | Value to be refunded to the paying user. | Positive numeric values with a period as the decimal separator. Example: \`119.10\` | — | Required | \*\*Key points to consider:\*\* - \*\*File format:\*\* the only accepted format is \`.csv\`. - \*\*Header row:\*\* fill in the first line with the headers shown in the table above. - \*\*Data separation:\*\* use a semicolon (\`;\`) to separate each field. - \*\*Valid amounts:\*\* values must be positive, consistent with the country's currency, and less than or equal to the original transaction value. - \*\*Special characters:\*\* special characters such as \`ñ\`, \`&\`, \`%\`, \`!\`, \`?\`, and similar are not allowed. - \*\*File name:\*\* use only letters, numbers, hyphens (\`-\`), underscores (\`\_\`), and periods (\`.\`). - \*\*File limits:\*\* the maximum size is 200,000 rows or 15 MB. If you have more rows, use multiple files. ::: :::AccordionComponent{title="Upload the refund file" pill="2"} After preparing and reviewing the file, upload it to the Mercado Pago interface. Only users with the \*\*Administrator\*\* role in your Mercado Pago account can perform this step. If you do not have this permission, contact your account administrator to make the upload or update your access level through the \*\*Collaborators\*\* section. To do so, access the URL provided by the Mercado Pago support team or your business representative and follow the steps below. \*\*1\. Upload the file:\*\* in the "Gestiona tus pagos de forma masiva" interface, select or drag the refund \`.csv\` file to the indicated area. !\[Refund file upload area in the Mercado Pago Portal\](https://www.mercadopago.com.mx/images/batch-payments/portal-upload-interface-es-v1.png) \*\*2\. Confirm the submission:\*\* verify that the selected file name is correct and click \*\*"Procesar archivo"\*\* to start processing the refunds. !\[Refund processing confirmation\](https://www.mercadopago.com.mx/images/batch-payments/portal-upload-confirmed-refund-es-v1.png) Mercado Pago applies automatic mechanisms to prevent duplicate file processing: - \*\*File name already used:\*\* it is verified whether the file name was already used in a previous processing. - \*\*Duplicate content:\*\* processing is blocked for files whose content is identical to another previously processed file. Although these automatic mechanisms exist, it is your responsibility to review the file name and content before uploading to avoid duplicate refunds. ::: :::AccordionComponent{title="Track refund processing" pill="3"} After the upload, Mercado Pago runs internal file validations and starts processing the refunds. \*\*24 hours after the upload\*\*, you can already check the updated processing status. > NOTE > > The processing time for all refunds depends on various factors, most of which are outside Mercado Pago's control. To find the results, access one of these options: - The main screen of \*\*"Gestiona tus pagos de forma masiva"\*\*, which shows the last uploaded file with its status and the "Consultar histórico" option, or - The full \*\*"Histórico de archivos"\*\* screen, accessible from "Consultar histórico". !\[Main bulk refund tracking screen\](https://www.mercadopago.com.mx/images/batch-payments/portal-tracking-main-es-v1.png) In "Histórico de archivos" you will find the file name, type (Reembolso), processing status, last update date, and the available action based on the status. !\[File history with refund processing statuses\](https://www.mercadopago.com.mx/images/batch-payments/portal-history-table-es-v1.png) The type of information available depends on the processing status: | Status | Action | Note | |:---:|:---:|---| | In process | Wait for completion | There are still refunds with a pending final result. Wait until processing is complete to download the final report. | | Processed | Download final file | Processing completed successfully. The final file with all results is available for download. | | File error | View error reasons | No refunds were created. The file contains incorrect data and there will be no report to download. Prepare the file again, making sure all required fields are included, the correct order and format are followed, and the file does not exceed 15 MB. | > WARNING > > Only the "Processed" status generates a result file for refunds. If an error occurs during processing, there will be no file available for download. Check the FAQs available in the interface or contact Mercado Pago support if you need help identifying the cause of the error. ::: :::AccordionComponent{title="Interpret the refund result file" pill="4"} Below is an example of the content you will find in the result file: \`\`\`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 \`\`\` | Header | Description | Format | Example | |---|---|---|---| | \`sequential\_order\` | Record order relative to the input file. | Numeric. | \`1\` | | \`external\_reference\` | Unique refund identifier sent in the input file. | Alphanumeric. | \`ext\_ref\_1\` | | \`amount\` | Amount refunded. | Positive numeric with decimal separators. | \`199,10\` | | \`refunds\_status\` | Refund status. | Alphanumeric. Possible values: \`Refunded\`, \`Invalid\`, \`Rejected\`. | \`refunded\` | | \`refund\_detail\` | Refund result detail. | Alphabetic. Possible values: \`refunded\`, \`The Payment ID entered is invalid\`, \`The amount entered is invalid\`, \`The external reference entered is invalid\`, \`The refund could not be processed\`. | \`refunded\` | | \`payment\_id\` | Payment identifier generated by Mercado Pago. | Numeric. | \`1885556854\` | For more information or assistance during the refund process, contact Mercado Pago support or your business representative. :::