mp-commerce-checkout

mp-commerce-checkout

Discover and integrate Mercado Pago Checkout Pro into an existing Python commerce-agent backend. Do not depend on a particular repository layout, framework, vertical, class name, or agent SDK.

The integration delegates the payment protocol to the exact published package mercadopago-commerce-agents-checkout==0.1.0. The host remains responsible for authentication, cart ownership, the authoritative catalog, durable checkout attempts, webhook verification, reconciliation, and fulfillment.

This is scaffolding. It must not make a live API request, create an Order, edit .env, or expose a credential. It has two mandatory phases: read-only discovery, then an explicitly confirmed apply phase.

Contract to preserve

agent proposes products and quantities
  -> authenticated seller backend confirms the cart
  -> backend durably persists external_reference + idempotency_key
  -> MercadoPagoCheckout rereads every product from the trusted catalog
  -> library creates and validates the Checkout Pro Order
  -> executor/UI receives CheckoutHandoff(checkout_url) after the model call
  -> verified Order webhook and server-side GET authorize fulfillment

The model must never receive the Access Token, idempotency key, seller reference, raw Order response, Order ID, or checkout_url. Creating an Order returns a buyer-controlled hosted payment step; it is not proof of payment.

Phase 1: read-only discovery

Run this phase first even when the developer asks to apply immediately. Do not write files, install packages, update lockfiles, or execute project code.

1. Establish project compatibility

Inspect manifests and source without importing the application:

• confirm the backend is Python and can run Python 3.11 or newer from project.requires-python, Poetry constraints, .python-version, runtime configuration, or an explicit developer confirmation;
• identify the dependency declaration and manager from uv.lock, poetry.lock, Pipfile, pyproject.toml, or requirements*.txt;
• distinguish runtime dependency files from development/test-only files;
• identify the server or worker entry point and the framework, if any.