MercadoPago Authentication: API Keys & OAuth 2.0 (2026)

Authentication overview

MercadoPago provides authentication mechanisms designed to secure API interactions, ensuring that only authorized applications can access and manipulate payment data. The choice of authentication method depends on the integration type and the scope of access required. For most server-to-server communications and direct API calls, developers utilize a combination of Public Keys and Access Tokens. When applications need to act on behalf of a MercadoPago user, such as accessing their account information or processing payments with their consent, OAuth 2.0 is the standard protocol employed.

These authentication methods are critical for maintaining the security and integrity of transactions processed through MercadoPago's platform, which adheres to PCI DSS Level 1 compliance, a global standard for payment card data security.

Supported authentication methods

MercadoPago supports two primary authentication methods tailored for different integration scenarios:

• API Keys (Public Key and Access Token): This method is suitable for most server-side integrations where your application directly interacts with MercadoPago APIs.
• OAuth 2.0: This protocol is used for applications that need to access a MercadoPago user's account with their explicit consent, without handling their credentials directly.

API Keys

API keys in MercadoPago consist of two distinct components:

• Public Key: This key is used on the client-side (e.g., in web browsers or mobile applications) to initialize MercadoPago's SDKs and encrypt sensitive payment data before it is sent to your server. It is safe to expose in client-side code because it only allows for the creation of tokens, not direct transaction processing.
• Access Token (formerly Private Key): This token is a confidential credential used on your server-side to make direct calls to MercadoPago's APIs, such as creating payments, managing refunds, or accessing account information. It grants full access to your MercadoPago account's API capabilities and must be kept strictly confidential.

For detailed guidance on using these keys, refer to the MercadoPago API Keys documentation.

OAuth 2.0

OAuth 2.0 is an authorization framework that allows a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access solely on its own behalf. For MercadoPago, OAuth 2.0 is primarily used by platforms or marketplaces that integrate with individual sellers' MercadoPago accounts.

The OAuth 2.0 flow typically involves:

1. The application redirects the user to MercadoPago's authorization page.
2. The user grants permission to the application.
3. MercadoPago redirects the user back to the application with an authorization code.
4. The application exchanges the authorization code for an Access Token and Refresh Token with MercadoPago.
5. The application uses the Access Token to make API calls on behalf of the user.

The OAuth 2.0 Authorization Framework RFC 6749 provides a comprehensive overview of this protocol.

The following table summarizes when to use each authentication method:

Getting your credentials

To obtain your MercadoPago authentication credentials, you need to access your MercadoPago Developer Dashboard.

1. Create an Account: If you don't already have one, sign up for a MercadoPago account.
2. Access Your Dashboard: Log in to your MercadoPago account and navigate to the "Your business" or "Developers" section.
3. Find Credentials: Look for a section labeled "Credentials" or "API Keys." Here, you will find both your Test credentials and Production credentials.
• Test credentials: These include a Test Public Key and a Test Access Token. Use these for development and testing purposes without affecting real transactions or funds.
• Production credentials: These include a Production Public Key and a Production Access Token. Use these only when your application is ready to go live and process real transactions. Production credentials are highly sensitive.
4. OAuth 2.0 Credentials: If you are building an application that uses OAuth 2.0, you will need to register your application within the developer dashboard to obtain a client_id and client_secret. These are typically found under an "Applications" or "Integrations" section.

It is crucial to distinguish between test and production credentials to prevent accidental live transactions during development. MercadoPago's test cards and users documentation provides resources for testing your integration thoroughly.

Authenticated request example

This example demonstrates how to make an authenticated API request to MercadoPago using an Access Token (API Key) in a Node.js environment. This type of request is typical for server-side operations, such as creating a payment.

const axios = require('axios');

const accessToken = 'YOUR_MERCADOPAGO_ACCESS_TOKEN'; // Replace with your actual Access Token
const paymentData = {
  transaction_amount: 100.00,
  description: 'Product purchase',
  payment_method_id: 'visa',
  payer: {
    email: '[email protected]'
  },
  installments: 1,
  token: 'YOUR_CARD_TOKEN' // Token generated on the client-side using Public Key
};

async function createPayment() {
  try {
    const response = await axios.post(
      'https://api.mercadopago.com/v1/payments',
      paymentData,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Payment created successfully:', response.data);
  } catch (error) {
    if (error.response) {
      console.error('Error creating payment:', error.response.data);
    } else {
      console.error('Error:', error.message);
    }
  }
}

createPayment();

In this example:

• YOUR_MERCADOPAGO_ACCESS_TOKEN must be replaced with your confidential Production Access Token.
• The Authorization header uses the Bearer scheme, which is standard for API token authentication, as described in RFC 6750 for Bearer Token Usage.
• YOUR_CARD_TOKEN represents a token generated on the client-side using the MercadoPago Public Key and SDKs, ensuring sensitive card data never touches your server directly.

For a complete list of endpoints and request structures, consult the MercadoPago API reference.

Security best practices

Adhering to security best practices is essential when integrating with MercadoPago to protect sensitive payment information and maintain compliance.

• Protect Access Tokens: Always treat your Access Tokens as highly confidential. Never expose them in client-side code, public repositories, or unsecured environments. Store them securely in environment variables, a secrets manager, or an encrypted configuration file.
• Use HTTPS: All communication with MercadoPago APIs must occur over HTTPS to ensure data encryption in transit. MercadoPago APIs enforce HTTPS, but verify your application also uses it for all outbound requests.
• Client-side Tokenization: Utilize MercadoPago's client-side SDKs (e.g., JavaScript SDK) to tokenize sensitive card data directly from the user's browser or mobile app. This ensures that raw card information never passes through your servers, significantly reducing your PCI DSS compliance scope.
• Implement Webhook Security: If you are using webhooks to receive notifications from MercadoPago, always verify the authenticity of incoming requests. MercadoPago signs its webhooks; validate these signatures to ensure the requests originate from MercadoPago and have not been tampered with.
• Principle of Least Privilege: Grant your application only the necessary permissions. If using OAuth 2.0, request only the scopes required for your application's functionality.
• Regular Audits: Periodically review your integration's security configurations and access logs. Rotate your API keys and tokens regularly, especially if there's any suspicion of compromise.
• Error Handling: Implement robust error handling without exposing sensitive details in error messages to end-users or logs.
• Stay Updated: Keep your MercadoPago SDKs and any related libraries updated to benefit from the latest security patches and features.

Following these guidelines helps to establish a secure and compliant integration with the MercadoPago platform.