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.
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.
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 comma 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_idandcard_idmust 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 (.).
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.
1. Upload the file: in the "Gestiona tus pagos de forma masiva" interface, select or drag the .csv file to the indicated area.
2. Confirm the submission: verify that the selected file name is correct and click "Procesar archivo" to start processing the charges.
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.
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.
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".
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.
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. |
Check the FAQs available in the interface or contact Mercado Pago support if you need help identifying the cause of the error.
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 |
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.
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 comma 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.
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.
2. Confirm the submission: verify that the selected file name is correct and click "Procesar archivo" to start processing the refunds.
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.
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.
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".
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.
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. |
Check the FAQs available in the interface or contact Mercado Pago support if you need help identifying the cause of the error.
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.