Install & Compatibility
Where this runs
tested against v3.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.706s · 21.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.1s · import 0.628s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SDK
✓ import mercadopago
sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")
✗ import mercadopago.MP
mp = mercadopago.MP("CLIENT_ID", "CLIENT_SECRET")
The `mercadopago.MP` class and `CLIENT_ID`/`CLIENT_SECRET` authentication are for older SDK versions (pre-2.x) and are deprecated. The current SDK (2.x+) uses `mercadopago.SDK` and requires an `ACCESS_TOKEN`.
RequestOptions
✓ from mercadopago.config import RequestOptions
This quickstart demonstrates how to initialize the Mercado Pago SDK with your access token and create a basic payment preference. Replace 'YOUR_ACCESS_TOKEN' with your actual production access token or set it as an environment variable `MERCADO_PAGO_ACCESS_TOKEN` for security. The example creates a checkout preference for a single item and prints the resulting payment links.
import os
import mercadopago
from mercadopago.config import RequestOptions
ACCESS_TOKEN = os.environ.get('MERCADO_PAGO_ACCESS_TOKEN', 'YOUR_ACCESS_TOKEN')
if not ACCESS_TOKEN or ACCESS_TOKEN == 'YOUR_ACCESS_TOKEN':
print("Error: MERCADO_PAGO_ACCESS_TOKEN environment variable is not set or is default.")
print("Please set it with your actual Mercado Pago Access Token.")
else:
try:
sdk = mercadopago.SDK(ACCESS_TOKEN)
# Example: Create a payment preference
preference_data = {
"items": [
{
"title": "My Product",
"quantity": 1,
"currency_id": "BRL",
"unit_price": 75.56
}
],
"payer": {
"email": "test_user_123456@testuser.com"
},
"back_urls": {
"success": "https://www.your-site.com/success",
"failure": "https://www.your-site.com/failure",
"pending": "https://www.your-site.com/pending"
},
"auto_return": "approved"
}
# Optional: Per-request configuration for custom headers or different credentials
# request_options = RequestOptions()
# request_options.custom_headers = { 'X-Idempotency-Key': 'some_unique_value' }
# result = sdk.preference().create(preference_data, request_options)
result = sdk.preference().create(preference_data)
if result["status"] == 201:
preference = result["response"]
print("Preference created successfully:")
print(f"ID: {preference['id']}")
print(f"Init Point: {preference['init_point']}")
print(f"Sandbox Init Point: {preference['sandbox_init_point']}")
else:
print(f"Error creating preference: {result['status']} - {result['response']}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingAuthentication mechanism changed from `CLIENT_ID`/`CLIENT_SECRET` to `ACCESS_TOKEN` in SDK version 2.x. Older code using `mercadopago.MP("CLIENT_ID", "CLIENT_SECRET")` will fail with the current SDK.fixInitialize the SDK using `sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")` and ensure you are using an `ACCESS_TOKEN` from your Mercado Pago credentials. affects: Older SDK versions migrating to 2.x+
gotchaWhen working with front-end components like Mercado Pago Checkout Bricks, the container ID provided to the Brick's creation function must exactly match an already rendered DOM element's ID. Mismatches or attempting to render before the DOM element is ready will result in a 'Container Not Found' error.fixEnsure the target HTML element with the specified ID exists and is fully rendered in the DOM before calling the Brick's render function. Classes are not accepted, only IDs.
affects: 2.x+
gotchaThe Customer Search API (`/v1/customers/search`) might return empty results even if a customer exists in the Mercado Pago dashboard. This can happen if the customer was created through a different flow (e.g., subscriptions) and is not linked to the 'customer' entity directly searchable by email.fixVerify the origin of the customer's creation. If issues persist, consider alternative methods like storing Mercado Pago customer IDs in your own system or reviewing official documentation for specific search limitations in different regions/flows.
affects: 2.x+
Errors
Common errors & fixes
TypeError: __init__() missing 1 required positional argument: 'access_token'
Attempting to initialize the `mercadopago.SDK` class without providing the `access_token` argument.
fixProvide your Mercado Pago access token when initializing the SDK: `sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")`. {'message': 'Invalid access_token', 'error': 'bad_request', 'status': 400}
The provided `ACCESS_TOKEN` is incorrect, expired, or malformed, leading to an authentication failure with the Mercado Pago API.
fixObtain a valid `ACCESS_TOKEN` from your Mercado Pago developer credentials panel (either production or test credentials) and ensure it is correctly passed to the SDK. Double-check for typos or leading/trailing spaces.
KeyError: 'response' or KeyError: 'status' when trying to access result['response'] or result['status']
The API call resulted in an unexpected response format, possibly due to a network error, a very specific API error not encapsulated as expected, or the SDK itself failing to structure the response.
fixAlways check if `result` is not `None` and contains expected keys before accessing them. Add more robust error handling around API calls. For example, `if 'response' in result and 'status' in result:`.
Upgrade
Version history
3.2.0latest on PyPI · released Jun 1, 2026
Audit
Dependencies
requestsrequiredUsed for making HTTP requests to the Mercado Pago API. Explicitly added as a required dependency in version 2.0.7.