{"id":9104,"library":"mercadopago","title":"Mercado Pago Python SDK","description":"The Mercado Pago SDK for Python provides developers with a simple set of bindings to integrate with the Mercado Pago API and process payments. It is actively maintained with frequent minor releases, currently at version 2.3.0, and simplifies server-side operations like creating and managing payment preferences, processing transactions, and handling refunds or chargebacks.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/mercadopago/sdk-python","tags":["payment","sdk","api","mercadopago","ecommerce"],"install":[{"cmd":"pip install mercadopago","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for making HTTP requests to the Mercado Pago API. Explicitly added as a required dependency in version 2.0.7.","package":"requests"}],"imports":[{"note":"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`.","wrong":"import mercadopago.MP\nmp = mercadopago.MP(\"CLIENT_ID\", \"CLIENT_SECRET\")","symbol":"SDK","correct":"import mercadopago\nsdk = mercadopago.SDK(\"YOUR_ACCESS_TOKEN\")"},{"symbol":"RequestOptions","correct":"from mercadopago.config import RequestOptions"}],"quickstart":{"code":"import os\nimport mercadopago\nfrom mercadopago.config import RequestOptions\n\nACCESS_TOKEN = os.environ.get('MERCADO_PAGO_ACCESS_TOKEN', 'YOUR_ACCESS_TOKEN')\n\nif not ACCESS_TOKEN or ACCESS_TOKEN == 'YOUR_ACCESS_TOKEN':\n    print(\"Error: MERCADO_PAGO_ACCESS_TOKEN environment variable is not set or is default.\")\n    print(\"Please set it with your actual Mercado Pago Access Token.\")\nelse:\n    try:\n        sdk = mercadopago.SDK(ACCESS_TOKEN)\n\n        # Example: Create a payment preference\n        preference_data = {\n            \"items\": [\n                {\n                    \"title\": \"My Product\",\n                    \"quantity\": 1,\n                    \"currency_id\": \"BRL\",\n                    \"unit_price\": 75.56\n                }\n            ],\n            \"payer\": {\n                \"email\": \"test_user_123456@testuser.com\"\n            },\n            \"back_urls\": {\n                \"success\": \"https://www.your-site.com/success\",\n                \"failure\": \"https://www.your-site.com/failure\",\n                \"pending\": \"https://www.your-site.com/pending\"\n            },\n            \"auto_return\": \"approved\"\n        }\n\n        # Optional: Per-request configuration for custom headers or different credentials\n        # request_options = RequestOptions()\n        # request_options.custom_headers = { 'X-Idempotency-Key': 'some_unique_value' }\n        # result = sdk.preference().create(preference_data, request_options)\n\n        result = sdk.preference().create(preference_data)\n\n        if result[\"status\"] == 201:\n            preference = result[\"response\"]\n            print(\"Preference created successfully:\")\n            print(f\"ID: {preference['id']}\")\n            print(f\"Init Point: {preference['init_point']}\")\n            print(f\"Sandbox Init Point: {preference['sandbox_init_point']}\")\n        else:\n            print(f\"Error creating preference: {result['status']} - {result['response']}\")\n\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Initialize the SDK using `sdk = mercadopago.SDK(\"YOUR_ACCESS_TOKEN\")` and ensure you are using an `ACCESS_TOKEN` from your Mercado Pago credentials.","message":"Authentication 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.","severity":"breaking","affected_versions":"Older SDK versions migrating to 2.x+"},{"fix":"Ensure 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.","message":"When 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.","severity":"gotcha","affected_versions":"2.x+"},{"fix":"Verify 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.","message":"The 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.","severity":"gotcha","affected_versions":"2.x+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Provide your Mercado Pago access token when initializing the SDK: `sdk = mercadopago.SDK(\"YOUR_ACCESS_TOKEN\")`.","cause":"Attempting to initialize the `mercadopago.SDK` class without providing the `access_token` argument.","error":"TypeError: __init__() missing 1 required positional argument: 'access_token'"},{"fix":"Obtain 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.","cause":"The provided `ACCESS_TOKEN` is incorrect, expired, or malformed, leading to an authentication failure with the Mercado Pago API.","error":"{'message': 'Invalid access_token', 'error': 'bad_request', 'status': 400}"},{"fix":"Always 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:`.","cause":"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.","error":"KeyError: 'response' or KeyError: 'status' when trying to access result['response'] or result['status']"}]}