MercadoPago SDKs & Libraries: Development Tools (2026)

SDKs overview

MercadoPago offers a suite of Software Development Kits (SDKs) designed to facilitate the integration of its payment processing capabilities into various applications. These SDKs abstract much of the complexity involved in direct API interactions, providing developers with pre-built functions for tasks such as creating payments, managing customers, handling refunds, and processing webhooks. The primary goal of these SDKs is to reduce development time and effort, allowing developers to focus on their application's core logic rather than the intricacies of payment gateway communication.

The official MercadoPago SDKs support a range of popular programming languages, ensuring broad compatibility for different development environments. Each SDK is maintained by MercadoPago and is regularly updated to reflect new features, security enhancements, and API changes. This commitment ensures that developers using the official SDKs have access to the most current and secure methods for integrating MercadoPago services. Developers can find detailed guides and API references on the MercadoPago developer documentation site.

For example, the SDKs handle critical security aspects like tokenizing sensitive card data directly from the client side, which helps merchants maintain PCI DSS compliance standards by minimizing exposure of raw card information on their servers. This client-side encryption is a common feature across many payment SDKs, including those from other major payment processors like Stripe's tokenization process.

Official SDKs by language

MercadoPago provides official SDKs for several widely used programming languages. These SDKs streamline the process of integrating payment solutions by offering methods and objects that correspond directly to MercadoPago API endpoints. Each SDK is designed to be idiomatic to its respective language, making it easier for developers to incorporate payment functionalities into existing projects.

The table below outlines the official SDKs, their typical package managers, and general installation commands:

Each SDK follows a consistent design pattern for authentication and interaction with the MercadoPago API. Typically, you initialize the SDK with your credentials (public key for client-side, access token for server-side) and then use its methods to perform operations like creating payment preferences, searching payments, or managing users. The MercadoPago API reference provides detailed information on available endpoints and expected parameters for each operation.

Installation

Installing MercadoPago SDKs typically involves using the standard package manager for your chosen programming language. Below are specific instructions for some of the most common languages, demonstrating the process for setting up the SDK in your development environment.

Node.js

For Node.js projects, the MercadoPago SDK is available via npm. Navigate to your project directory and run:

npm install mercadopago

After installation, you can import and configure the SDK in your JavaScript files:

const mercadopago = require('mercadopago');

// Configure client
mercadopago.configure({
  access_token: 'YOUR_ACCESS_TOKEN'
});

PHP

PHP projects typically use Composer for dependency management. To install the MercadoPago PHP SDK, execute the following command in your project's root directory:

composer require mercadopago/dx-php

Once installed, you can include the autoloader and configure the SDK:

<?php
require __DIR__ . '/vendor/autoload.php';

MercadoPago\SDK::setAccessToken('YOUR_ACCESS_TOKEN');

// Or for a more modern approach with an object:
// $client = new MercadoPago\Client\MercadoPagoClient('YOUR_ACCESS_TOKEN');
?>

Python

Python developers can install the SDK using pip:

pip install mercadopago

Then, set up the SDK in your Python scripts:

import mercadopago

# Configure client
mercadopago.configure(
    access_token='YOUR_ACCESS_TOKEN'
)

Java

For Java projects, you typically add the MercadoPago SDK as a dependency in your pom.xml (Maven) or build.gradle (Gradle) file. Here's an example for Maven:

<dependencies>
    <dependency>
        <groupId>com.mercadopago</groupId>
        <artifactId>sdk-java</artifactId>
        <version>2.1.0</version> <!-- Check for the latest version -->
    </dependency>
</dependencies>

After adding the dependency, configure the SDK in your Java code:

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.preference.PreferenceClient;
import com.mercadopago.resources.preference.Preference;

public class PaymentProcessor {
    public PaymentProcessor() {
        MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");
    }
}

It's important to replace 'YOUR_ACCESS_TOKEN' with your actual MercadoPago access token, which can be obtained from your MercadoPago developer credentials page. For client-side integrations, a public key is used instead of an access token to ensure sensitive information remains secure and does not expose your server-side credentials.

Quickstart example

This quickstart example demonstrates how to create a basic payment preference using the MercadoPago Node.js SDK. A payment preference defines the details of a transaction, such as item descriptions, prices, and buyer information. This is a common first step when integrating MercadoPago for online payments, especially for generating a checkout link or embedding a payment button.

Before running this example, ensure you have Node.js and the mercadopago SDK installed as described in the installation section.

const mercadopago = require('mercadopago');

// Configure your MercadoPago access token
mercadopago.configure({
  access_token: 'YOUR_ACCESS_TOKEN'
});

async function createPaymentPreference() {
  try {
    const preference = {
      items: [
        {
          title: 'My product',
          unit_price: 100,
          quantity: 1,
        },
      ],
      back_urls: {
        success: 'http://localhost:3000/feedback',
        failure: 'http://localhost:3000/feedback',
        pending: 'http://localhost:3000/feedback',
      },
      auto_return: 'approved_or_pending',
      notification_url: 'https://your-server.com/webhooks/mercadopago',
      external_reference: 'some_unique_order_id_123',
      payer: {
        email: '[email protected]',
      },
    };

    const response = await mercadopago.preferences.create(preference);
    console.log('Preference created:', response.body);
    console.log('Checkout link:', response.body.init_point);
    return response.body.init_point;
  } catch (error) {
    console.error('Error creating preference:', error);
  }
}

createPaymentPreference();

In this example:

• mercadopago.configure(): Initializes the SDK with your private access token. This token authenticates your requests to the MercadoPago API.
• preference object: Defines the payment details.
• items: An array describing the products or services being purchased, including title, unit price, and quantity.
• back_urls: Specifies the URLs where the user will be redirected after completing, failing, or pending a payment.
• auto_return: Determines when the user is automatically redirected back to your site. 'approved_or_pending' means redirection happens after an approved or pending payment.
• notification_url: This is a crucial webhook URL where MercadoPago will send asynchronous notifications about payment status changes. Receiving and processing these notifications is essential for updating your order status reliably, as users might close their browser before being redirected to back_urls.
• external_reference: A unique identifier from your system for this transaction, useful for reconciliation.
• payer: Contains information about the buyer, such as their email address.
• mercadopago.preferences.create(preference): Sends the preference object to MercadoPago to create the payment intent.
• The response includes init_point, which is the URL for the MercadoPago checkout page. You can redirect your users to this URL to complete the payment.

Remember to replace 'YOUR_ACCESS_TOKEN' and the example URLs with your actual values. For production environments, ensure your notification_url is a secure, publicly accessible endpoint on your server that can handle incoming webhook requests from MercadoPago. Processing webhooks correctly is vital for robust payment system integration, as outlined in MercadoPago's webhook notification guide.

Community libraries

While MercadoPago provides a comprehensive set of official SDKs, the developer community also contributes various libraries and tools that can complement or extend the official offerings. These community-driven projects often address niche use cases, provide specific framework integrations (e.g., for specific e-commerce platforms or frontend frameworks not directly covered by official SDKs), or offer alternative abstractions.

Community libraries can be identified through platforms like GitHub, npm, Packagist, or rubygems.org by searching for "MercadoPago" combined with specific framework names (e.g., "MercadoPago Laravel" or "MercadoPago React Native"). Some examples include:

• Framework-specific integrations: Developers often create packages that integrate MercadoPago SDKs more seamlessly into popular frameworks like Laravel (PHP), Django (Python), or Ruby on Rails. These integrations might offer pre-built controllers, views, or service providers that abstract common tasks within the framework's architecture.
• Frontend components: Beyond the official JavaScript SDK (@mercadopago/sdk-js) and React SDK (@mercadopago/sdk-react), community members might develop components for other frontend frameworks like Vue.js or Angular, providing wrappers or custom elements to simplify client-side payment form rendering and tokenization.
• E-commerce platform plugins: While MercadoPago offers official plugins for major platforms like WooCommerce and Magento, a vibrant community contributes plugins for smaller or more specialized e-commerce systems, extending MercadoPago's reach.
• API wrappers with different paradigms: Some community libraries might offer alternative API wrappers that align with different programming paradigms or design patterns, which some developers might find more intuitive for their specific project needs.

When considering community libraries, it is crucial to evaluate their maintenance status, community support, and alignment with the latest MercadoPago API versions and security practices. Always review the source code and documentation carefully, and prioritize libraries with active development and clear licensing. While official SDKs are recommended for core integrations due to direct vendor support and adherence to security best practices, community libraries can offer valuable flexibility and specialized solutions.