Mercado Pago Python SDK

To protect your account and comply with security policies, NEVER share the following information in public GitHub issues:

• Access tokens or production credentials.
• Client IDs / Client Secrets.
• Customer or card data.
• Personally Identifiable Information (PII).

Note: Issues containing real sensitive data will be closed and reported immediately.

Install the SDK using pip. Ensure you are using Python 3.9 or higher.

pip3 install mercadopago

To use the SDK, instantiate the mercadopago.SDK class with your Access Token obtained from the Mercado Pago credentials panel.

import mercadopago

sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")

To use the Mercado Pago SDK, instantiate the SDK class with your OAuth access token. This central client provides factory methods to access all Mercado Pago API resources (such as payments, orders, and customers).

By default, the SDK uses a built-in HttpClient based on requests and applies default RequestOptions (timeout, retries, etc.) to all requests.

import mercadopago

sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")

To interact with the MercadoPago REST API, import the SDK class from mercadopago and initialize it with your access token. Once initialized, you can access various API resources (like payment()) to perform operations such as creating payments.

import mercadopago

sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")
# Example: Creating a payment
payment = sdk.payment().create({
    # ... payment data
})

For better type safety, use the provided dataclasses from mercadopago.resources. Fields set to None are automatically omitted from the resulting JSON body.

import mercadopago
from mercadopago.resources.order_create import OrderCreateRequest, OrderPayerRequest
from mercadopago.resources.order_item import OrderItemRequest

sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")

order = OrderCreateRequest(
    type="online",
    total_amount="100.00",
    external_reference="ext_ref_1234",
    payer=OrderPayerRequest(email="test_user_123456@testuser.com"),
    items=[OrderItemRequest(title="A book", unit_price="100.00", quantity=1)],
)

result = sdk.order().create(order)
print(result["response"])

You can use the legacy Payments API via sdk.payment().create() by passing a dictionary containing payment details.

import mercadopago

sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")

payment_data = {
    "transaction_amount": 100,
    "token": "CARD_TOKEN",
    "description": "Payment description",
    "payment_method_id": 'visa',
    "installments": 1,
    "payer": {
        "email": 'test_user_123456@testuser.com'
    }
}
result = sdk.payment().create(payment_data)
payment = result["response"]
print(payment)

All API methods accept an optional RequestOptions object. This allows you to override credentials (like access_token) or provide custom_headers (such as an x-idempotency-key) for a specific request.

import mercadopago
from mercadopago.config import RequestOptions

sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")

# Example 1: Using custom headers for idempotency
request_options = RequestOptions()
request_options.custom_headers = {
    'x-idempotency-key': '<SOME_UNIQUE_VALUE>'
}

# Example 2: Overriding the access token for a specific request
request_options_alt = RequestOptions(access_token='YOUR_ACCESS_TOKEN')

# Applying options to a call
payment_data = {"transaction_amount": 100, "token": "CARD_TOKEN", "payment_method_id": "visa", "installments": 1}
result = sdk.payment().create(payment_data, request_options)

Use these resources for technical guidance and status updates:

• Official Documentation: Complete guides.
• API Reference: Detailed API specifications.
• SDKs Library: Information on other available SDKs.
• Service Status Page: Check the current status of Mercado Pago services.
• Discord: Join the community channel.

The SDK class acts as a factory. Each factory method returns a fresh resource instance bound to the SDK's credentials and HTTP client. You can call these methods to interact with specific parts of the Mercado Pago API.

Example of creating a payment using the payment() factory method:

import mercadopago

sdk = mercadopago.SDK("YOUR_ACCESS_TOKEN")
result = sdk.payment().create({
    "transaction_amount": 100,
    "payment_method_id": "pix",
    "payer": {"email": "buyer@example.com"},
})