> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mercado Pago as a data source
> Bring payments, fees and the Releases and Account money reports from Mercado Pago to Nekt.
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](https://app.nekt.ai/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](https://www.mercadopago.com.br/developers/panel/app) 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](https://www.mercadopago.com.br/balance/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](https://docs.nekt.com/runs/scheduling-and-triggers), 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](https://docs.nekt.com/get-started/core-concepts/resource-control).
* **Do not enable an Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#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](https://app.nekt.ai/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](https://app.nekt.ai/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.
| Stream | Slug | Description |
| - | - | - |
| Payments | `payments` | Payments received (and made) by the account, with amounts, fees, net amount, status and money release date. Last 12 months on the first sync. |
| Payment Fees | `payment_fees` | One row per fee charged on each payment (Mercado Pago fee, installment financing fee, and others). |
| Payment Charges | `payment_charges` | One row per detailed charge applied to each payment. |
| Payment Refunds | `payment_refunds` | One row per refund of each payment. |
| Releases Reports | `release_reports` | Releases report files that exist in the account (period, creation date, status). |
| Releases Report Rows | `release_report_rows` | Every line of the Releases report files: each movement of the available balance (releases, fees, refunds, disputes, withdrawals). |
| Account Money Reports | `settlement_reports` | Account money report files that exist in the account. |
| Account Money Report Rows | `settlement_report_rows` | Every line of the Account money report files: each transaction that affected the money in the account, with gross amount, fees, net amount and release date. |
## 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
| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "Mercado Pago rejected the Access Token" | The token is wrong, was renewed, or is a test credential. | Copy the production Access Token again from **Your integrations > Production credentials** and update the source. |
| Report streams have no data | No report file exists in the account for the period. | Generate the Releases or Account money report in Mercado Pago and run the source again. |
| A report stream was skipped with a permission warning | Mercado Pago did not allow the token to read that report. | Confirm that the token belongs to the account that owns the reports. |
| The run stopped while reading a report | Mercado Pago refused one page or file in the middle of the run, so nothing partial was loaded. | Run the source again. If it repeats, check the token's access to the reports. |
| The run stopped saying too many payments were updated in one second | Mercado Pago's search cannot page through that many payments at once. | Contact Nekt support. |
| Warning: payments were not returned in the expected order and are read in smaller time slices | Mercado Pago ignored or refused the order the connector asks for. The sync still reads every payment, with more requests. | No action needed. If syncs become too slow, contact Nekt support. |
| The run stops every time on the same report file | Mercado Pago refuses that file (permission error) on every attempt. | Deselect the report rows stream (`release_report_rows` or `settlement_report_rows`) so the other streams keep syncing, and contact Nekt support. |
| Warning: the decimal separator of a report file could not be determined | The first rows of that file do not show whether it uses dot or comma decimals. | Amounts that read both ways are empty in their column; use the value in `row_data`. |
| Report columns are empty but `row_data` is filled | The report headers are not in English. | Set the report language to English in the report settings in Mercado Pago. |
## Skills for agents
Mercado Pago connector documentation as plain markdown, for use in AI agent contexts.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.