---

✨ What can you do with this node?

Resource	What you get
💳 Payments	Create Checkout Preference links with items, back URLs, expiration dates and more
📊 Reporting	Configure, list and download Release & Settlement reports

---

🗺️ Operations at a glance

💳 Payments

Operation	Method	Description
Create Payment Link	POST	Generate a Checkout Preference link to accept payments

📊 Reporting — Release Reports

Operation	Method	Description
List Release Reports	GET	List generated report files (supports pagination & returnAll)
Configure Release Report	POST / PUT	Create or update preferences — columns, frequency, SFTP delivery
Get Release Report Config	GET	Read the current configuration for your account
Download Release Report	GET	Download a specific report file as CSV

📊 Reporting — Settlement Reports

Operation	Method	Description
List Settlement Reports	GET	List generated settlement report files
Configure Settlement Report	POST / PUT	Create or update preferences — columns, frequency, SFTP delivery
Get Settlement Report Config	GET	Read the current configuration for your account
Download Settlement Report	GET	Download a specific settlement report file as CSV

💡 Smart configure: The Configure operations are upsert — they automatically create the config if it doesn't exist yet, or update it if it does. No need to know what state you're in.

---

🚀 Quick start

1. Install the node

In your n8n instance go to Settings → Community Nodes → Install and enter:

@mercadopago/n8n-nodes-mercadopago

2. Set up your credential

1. In n8n go to Credentials → New → search for MercadoPago API
2. Paste your Access Token (found in the Mercado Pago Developer Portal)
3. Click Test credential — you'll get a green ✅ if it's valid

Optional — SFTP delivery: If you want reports delivered automatically to an SFTP server, create a MercadoPago SFTP credential with the connection details and attach it to the node.

3. Build your first workflow

Trigger → MercadoPago (Create Payment Link) → Send email with payment URL

Schedule → MercadoPago (List Release Reports) → Filter → Save to Google Sheets

---

📋 Operation details

💳 Create Payment Link

Creates a Checkout Preference — a hosted payment page with your items.

Required:

• At least one Item (title, quantity, currency, unit price)

Optional fields:

• external_reference — your internal order ID (max 64 chars)
• notification_url — HTTPS webhook for payment status updates
• back_urls — redirect URLs for success / pending / failure
• auto_return — auto-redirect after approved payment
• expiration_date_from / expiration_date_to — limit when the link is valid
• statement_descriptor — text on the buyer's bank statement (max 13 chars)
• binary_mode — only approved/rejected (no pending)

📊 Configure Release Report

Sets up automatic Release Report generation for your account. Works as an upsert — safe to run multiple times.

Required:

• Columns — at least one column key (e.g. DATE, SOURCE_ID, NET_CREDIT_AMOUNT)
• File Name Prefix — prefix for generated file names
• Frequency — hour (0–23), interval value, and type (daily / weekly / monthly)

Optional:

• SFTP credential for automatic file delivery
• separator, display_timezone, report_translation
• Email notification list
• Boolean flags: include_withdrawal_at_end, check_available_balance, compensate_detail, execute_after_withdrawal, scheduled

📊 Configure Settlement Report

Same as Configure Release Report but for Settlement Reports. Supports a different set of columns and fewer boolean flags.

⬇️ Download Report (Release or Settlement)

Downloads a generated report file by name.

• Returns a JSON object with a content field containing the raw CSV string
• Pipe this into a Write Binary File node or a Code node to process it

---

🔐 Credentials

MercadoPago API (required)

Field	Description
Access Token	Your Bearer token from the Mercado Pago Developer Portal

Get your token at: mercadopago.com.br/developers → Your integrations → Credentials

MercadoPago SFTP (optional)

Only needed if you configure SFTP delivery for reports.

Field	Description
Server	SFTP hostname or IP
Username	SFTP login
Password	SFTP password (stored encrypted)
Remote Dir	Destination directory on the SFTP server
Port	Default: 22

---

🏗️ Architecture

The node follows a modular handler pattern where each operation lives in its own file.

credentials/
  MercadoPagoApi.credentials.ts    ← API access token credential
  MercadoPagoSftp.credentials.ts   ← Optional SFTP credential

nodes/MercadoPago/
  MercadoPago.node.ts              ← Node definition, UI properties, request wrapper
  MercadoPago.node.json            ← Metadata (categories, docs links)
  icon-mercadopago.svg
  icon-mercadopago.dark.svg
  operations/
    index.ts                       ← Handler registry + shared types (HandlerCtx)
    utils.ts                       ← Shared parsing helpers
    createPaymentLink.ts
    listReleaseReports.ts
    configureReleaseReport.ts      ← Upsert: POST → fallback PUT on 409
    getReleaseReportConfig.ts
    downloadReleaseReport.ts
    listSettlementReports.ts
    configureSettlementReport.ts   ← Upsert: POST → fallback PUT on 409
    getSettlementReportConfig.ts
    downloadSettlementReport.ts

tests/operations/                  ← Vitest unit tests (one per operation)

How operations work:

execute() in MercadoPago.node.ts
  └── builds HandlerCtx (credential, request wrapper, helpers)
  └── dispatches to operations[operationName](ctx)
      └── handler validates input → builds body → calls ctx.request()
          └── makeRequest() adds Auth header, handles httpRequest

---

🛠️ Development

Prerequisites

• Node.js >= 20.15
• npm

Commands

npm install          # Install dependencies
npm run build        # Compile TypeScript → dist/
npm run test:unit    # Run unit tests once
npm run test         # Run tests in watch mode
npm run test:coverage # Generate coverage report
npm run lint         # ESLint
npm run format       # Prettier

Adding a new operation

1. Create nodes/MercadoPago/operations/myOperation.ts
2. Implement the handler using HandlerCtx
3. Register it in operations/index.ts
4. Add UI properties to MercadoPago.node.ts
5. Write tests in tests/operations/myOperation.test.ts

---

🤝 Contributing

Contributions are welcome! Read CONTRIBUTING.md to learn about the development process, branching model, and how to submit a pull request.

---

📄 License

MIT — maintained by the Tech Stuff IXF team at Mercado Pago.