Skip to main content
Mercado Pago is the payments platform of Mercado Livre, used to receive online and in-person payments (card, Pix, boleto and account money) and to receive the sales made on Mercado Livre. This connector brings the payments of your Mercado Pago account, with their fees, net amounts and release dates, plus the files of the Releases report (relatório de liberações) and the Account money report that exist in your account, line by line. It is useful for reconciling receipts with your ERP or accounting system and for analyzing fees, including the fee for releasing money in advance.
The connector only reads data. It never creates payments, generates reports or changes report settings in your Mercado Pago account.

​
Configuring Mercado Pago as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Mercado Pago option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

The connector uses the production Access Token of an application created by the Mercado Pago account whose data you want to extract. To get it:
  1. Log in to Mercado Pago Developers with the Mercado Pago account that receives the payments (for Mercado Livre sellers, the account linked to your Mercado Livre store).
  2. Open Your integrations and select an application, or create one.
  3. In the left menu, open Production credentials. If they are not active yet, fill in the industry and website of your business and click Activate production credentials.
  4. Copy the Access Token. It starts with APP_USR-.
The following configurations are available:
  • Access Token: The production Access Token copied above. Do not use a test credential: test accounts return no report data.
  • Start Date: (Optional) The earliest date to extract on the first sync: payments updated and report files generated on or after this date. Mercado Pago’s payment search only returns the last 12 months, so payments always start at most 12 months back. Leave it empty to read the last 12 months of payments and every report file in the account.
The Releases and Account money report streams read only report files that already exist in your Mercado Pago account. Generate them in Mercado Pago, under Sales and billing > Reports (Releases or Account money), for the periods you need. In the Releases report settings, Mercado Pago can also generate a Releases report automatically every time you withdraw money. Scheduled generation (daily, weekly or monthly) is configured through Mercado Pago’s reports API, not by this connector. Each sync loads the files created since the previous one.
Once you’re done, click Next.

​
2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data, which is good if, for example, you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data, which is good if, for example, you don’t want to have deleted data in your catalog.
Keep the Payments stream (and the payment fees, charges and refunds streams) as INCREMENTAL. Mercado Pago only returns the last 12 months of payments, so a full table sync replaces the table with those 12 months and older payments are removed from it. The same happens on a manual full sync of the source. The sync log shows a warning whenever payments are read this way.
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Do not enable an Additional Full Sync for this source. A full sync of the payment streams only reaches the last 12 months (Mercado Pago’s limit), so each one would remove older payments from your tables. The same applies to a full sync triggered manually.
Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
Streams and Fields

​
Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description.

​
Fields by stream

One row per payment, updated incrementally by the date of its last change.Identification:
  • id - Unique identifier of the payment
  • external_reference - Reference sent when the payment was created (for example, your order number), used to reconcile with other systems
  • order_id - Order linked to the payment, such as the Mercado Livre order id
  • order_type - Type of the linked order (for example, mercadolibre)
  • collector_id - Mercado Pago account that received the payment
  • description - Description of the payment
Dates (UTC):
  • date_created - When the payment was created
  • date_approved - When the payment was approved
  • date_last_updated - When the payment was last updated (incremental key)
  • date_of_expiration - Date after which the payment can no longer be paid (boleto, Pix)
  • money_release_date - Date the money is (or was) released to the available balance
  • money_release_status - Status of the money release (for example, released or pending)
Amounts:
  • transaction_amount - Gross amount of the payment
  • net_received_amount - Net amount received after Mercado Pago fees
  • total_paid_amount - Total paid by the buyer, including interest and shipping
  • transaction_amount_refunded - Total refunded
  • installments / installment_amount - Number and amount of installments
  • coupon_amount, shipping_amount, taxes_amount, net_amount, overpaid_amount - Other amounts of the payment
  • currency_id - Currency (for example, BRL)
Status and method:
  • status - Payment status (approved, pending, rejected, refunded, charged_back, …)
  • status_detail - Detail of the status (for example, accredited)
  • payment_method_id - Payment method (for example, visa, pix, bolbradesco)
  • payment_type_id - Payment method type (credit_card, debit_card, bank_transfer, ticket, …)
  • operation_type - Operation type (regular_payment, money_transfer, …)
Payer:
  • payer_id, payer_email, payer_identification_type, payer_identification_number - Payer of the payment
Details as JSON text:
  • fee_details - Fees charged on the payment
  • charges_details - Detailed charges
  • refunds - Refunds
  • transaction_details, payer, order, payment_method, card, point_of_interaction, additional_info, metadata, taxes, three_ds_info - Nested objects as returned by Mercado Pago
  • additional_fields - Fields returned by Mercado Pago that have no column of their own
One row per fee of a payment.
  • payment_id - Payment the fee belongs to; join to payments.id
  • fee_index - Position of the fee in the payment’s fee list. Fees have no id of their own, so payment_id + fee_index identifies the row
  • type - Fee type (for example, mercadopago_fee, financing_fee, application_fee)
  • amount - Fee amount
  • fee_payer - Who pays the fee: collector (the seller) or payer (the buyer)
  • currency_id - Currency of the payment
  • payment_date_last_updated - Last update of the payment (incremental key)
One row per detailed charge of a payment.
  • payment_id, id - Payment and identifier of the charge (together they identify the row)
  • name, type - Name and type of the charge
  • amount_original, amount_refunded - Charged and refunded amounts
  • account_from, account_to - Accounts the charge moves between
  • date_created, last_updated - Dates of the charge
  • client_id, reserve_id, metadata, refund_charges - Other details
  • currency_id, payment_date_last_updated - Currency and last update of the payment (incremental key)
One row per refund of a payment.
  • payment_id, id - Payment and identifier of the refund (together they identify the row)
  • amount, amount_refunded_to_payer, adjustment_amount - Refunded amounts
  • status, reason, refund_mode - Status, reason and mode of the refund
  • date_created - When the refund was created
  • source - Who requested the refund (JSON text)
  • unique_sequence_number, metadata - Other details
  • currency_id, payment_date_last_updated - Currency and last update of the payment (incremental key)
One row per report file that exists in the account.
  • id - Identifier of the report
  • file_name - Name of the report file
  • date_created - When the report was generated (incremental key)
  • begin_date, end_date - Period covered by the report
  • created_from - manual or schedule
  • status, origin, model, sub_type, format, currency_id - Report details
  • user_id, account_id - Owner of the report
  • download_date - When the file was last downloaded
  • metadata, additional_fields - Extra information as JSON text
One row per line of each Releases report file. The report is a ledger of the available balance: besides the movements, it has balance, block, subtotal and total lines (see record_type).Row identification:
  • report_id, row_number - Report and position of the line in its file (together they identify the row)
  • report_file_name, report_date_created, report_begin_date, report_end_date - File the line came from
Report columns (named after the report’s English column headers, in lowercase):
  • date - Release date: when the movement impacted the available balance
  • source_id - Transaction id in Mercado Pago, such as the payment id
  • external_reference - Reference of the origin, such as the Mercado Livre order or shipment id
  • order_id, pack_id, shipping_id - Order, cart and shipment ids
  • record_type - initial_available_balance (balance at the start of the period), release (money released), block and unblock (money held and freed by disputes), subtotal (sum of a section), total, or available_balance (balance before and after a withdrawal)
  • description - Movement: payment, refund, chargeback, dispute, shipping, payout, reserve_for_..., and fee-release_in_advance for the fee charged to release money in advance
  • net_credit_amount, net_debit_amount - Net amount credited to or debited from the available balance
  • gross_amount - Gross amount of the operation
  • mp_fee_amount, financing_fee_amount, shipping_fee_amount, taxes_amount, coupon_amount, effective_coupon_amount, tax_amount_telco - Fees, costs and taxes
  • balance_amount - Balance after the movement
  • installments, payment_method, payment_method_type, transaction_date, transaction_approval_date - Operation details
  • Other columns of the glossary when present in your report (store, POS, card, SKU, sale detail, and others)
  • row_data - The whole line as JSON text, keyed by the column headers of the file
One row per line of each Account money report file.Row identification:
  • report_id, row_number - Report and position of the line in its file (together they identify the row)
  • report_file_name, report_date_created, report_begin_date, report_end_date - File the line came from
Report columns (named after the report’s English column headers, in lowercase):
  • source_id - Transaction id in Mercado Pago, such as the payment id
  • external_reference - Reference of the origin, such as the Mercado Livre order or shipment id
  • order_id, pack_id, shipping_id - Order, cart and shipment ids
  • transaction_type - SETTLEMENT (approved payment), REFUND, CHARGEBACK, DISPUTE, WITHDRAWAL, PAYOUT, and others
  • transaction_amount - Purchase amount
  • fee_amount - Fees paid by the seller (processing, shipping, installments and coupon)
  • mkp_fee_amount, financing_fee_amount, shipping_fee_amount, taxes_amount, coupon_amount - Fees, costs and taxes in detail
  • settlement_net_amount - Net amount that impacted the balance
  • real_amount - Net amount after chargebacks, disputes and refunds
  • transaction_date, settlement_date, money_release_date - Creation, approval and release dates
  • is_released - Whether the money was already released
  • installments, installment_number, installment_net_amount - Installment details
  • payment_method, payment_method_type, business_unit, sub_unit - Payment channel details
  • Other columns of the glossary when present in your report (store, POS, card, SKU, sale detail, and others)
  • row_data - The whole line as JSON text, keyed by the column headers of the file

​
Implementation Notes

​
Data Quality Considerations

  • Payments: Mercado Pago’s payment search only returns payments from the last 12 months. Older history is available in the Releases and Account money report files generated for those periods.
  • Report rows: amount columns are loaded as numbers, reading each file with its own decimal separator (1.300,00 in a file with comma decimals, 1,300.00 in a file with dot decimals). If the first rows of a file do not show which separator it uses, amounts that read both ways (such as 1.300 or 1,300) are left empty in their column, the original text stays in row_data, and the sync log shows a warning for that file. Every other column is loaded as text exactly as written in the file, including dates, which follow the timezone configured in your report settings (GMT-4 by default). If a column name appears twice in a file, row_data keeps both (the second with a _2 suffix).
  • The fee for releasing money in advance (antecipação) appears in the Releases report as its own line, with description equal to fee-release_in_advance. Join it to the payment line by source_id, external_reference or order_id.
  • If your reports are set to a language other than English, the column headers are not recognized: every value is still loaded in row_data, and the sync log shows a warning. Set the report language back to English in Mercado Pago’s report settings (or contact Nekt support) to get each value in its own column.
  • Reports generated for the same period more than once produce one set of rows per file. Use report_id or the report period to keep only one of them.
  • If you set a report rows stream (or a payment fees, charges or refunds stream) to FULL_TABLE, each sync reads every file (or payment) since the Start Date, because the table is replaced with what that sync reads.

​
API Limits & Performance

  • The payment search returns at most 50 payments per request, so the first sync of a large account can take a while. Later syncs only read payments updated since the previous one.
  • If Mercado Pago does not return payments in the order the connector asks for, the sync switches to reading payments in smaller time slices. Nothing is skipped, but the sync makes about 2 to 4 times more requests and takes longer; the sync log shows a warning when this happens.
  • Each report file covers up to 60 days. Every sync re-reads the files generated in the last 2 days, so that files still being generated during one sync are loaded by the next.

​
Troubleshooting

​
Skills for agents

Download Mercado Pago skills file

Mercado Pago connector documentation as plain markdown, for use in AI agent contexts.