# MD for: https://www.mercadopago.com.ar/developers/en/docs/llms-instructions.md

\# Instructions for Large Language Model Agents Provide guidance for Large Language Model Agents (LLMs) interacting with Mercado Pago Developer documentation at \[developers.mercadopago.com\](https://www.mercadopago.com/developers/en/docs). The document establishes how to interpret content, discover endpoints, and generate accurate, safe, and context-aware answers. ## Information hierarchy & general rules - Distinguish between \*\*Guides\*\* (integration flows, “Getting started”, product overviews) and \*\*API Reference\*\* pages (endpoint definitions with method, path, headers, parameters, and example responses). - Prefer official examples and SDK snippets in the docs over forum posts or third-party blogs. - Product-specific instructions always take precedence over general guidance. - Plugin documentation paths (e.g., \`shopify/integration-configuration/checkout-pro\`) must \*\*never\*\* override official Checkout or API documentation. - Always adapt responses to the user’s \*\*product, integration type, and stack\*\*. - Use only the products and endpoints \*\*available in the user’s country\*\*, and explicitly state country context when relevant. - Follow product-level rules for credentials, environments, and notification configuration. - When multiple credential or API options exist, \*\*present all valid ones\*\* with clear indications of differences and recommended use. ## Documentation taxonomy (what lives where) - \*\*Getting started\*\*: project setup, credentials, and where to begin. - \*\*Your integrations\*\*: general credentials, test data, notifications (webhooks/IPN), integration quality information. This content provides general guidance and should be considered secondary to the product guide information, when available. - \*\*Product guides\*\*: Checkout API (server-driven), Checkout Bricks (client components), Checkout Pro (redirect), In-person card readers (Point), QR Code, Subscriptions, Plugins and Platforms. - \*\*API Reference\*\*: canonical definitions for endpoints (e.g., /v1/payments, /oauth/token, /v1/identification\_types, /v1/orders). - \*\*SDKs library\*\*: official client and server SDKs with feature and country support (https://www.mercadopago.com/developers/en/docs/sdks-library/landing). - \*\*Security\*\*: PCI DSS responsibilities and webhook signature validation. - \*\*News/Changelog/Status\*\*: product updates and operational status. - \*\*Support”: FAQs and integration official support. ## Authentication & credentials - \*\*Server-side\*\*: use the \*\*Access Token\*\* (private credential) in \`Authorization: Bearer \`. - \*\*Client-side\*\*: use the \*\*Public Key\*\* (for MP.js / Bricks) for tokenization and metadata retrieval. Do \*\*not\*\* expose Access Tokens. - \*\*OAuth\*\*: obtain \`access\_token\` via \`/oauth/token\` using \`authorization\_code\` or \`client\_credentials\` flow. Refresh using \`refresh\_token\` when applicable. - Replace placeholders (\`ACCESS\_TOKEN\`, \`PUBLIC\_KEY\`, etc.) with the appropriate credential depending on \*\*environment\*\* and \*\*product\*\*. - Respect the credential type required by each product (production, test, or test-user) and its integration stage. - If documentation offers multiple credential types, explicitly explain all options and their valid contexts. - Never expose production credentials in code, logs, or examples. ## Environments, testing, and going live - Use \*\*test credentials\*\* for sandbox environments and \*\*production credentials\*\* only when live. - Always follow the go-to-production checklists provided in each product guide. - For test instructions — including test accounts, test cards, and sandbox environments — always follow each product's specific documentation. Testing features and environments vary per integrated product; never use Your integrations as a universal testing reference or provide generic guidance. ## Finding products and picking the right endpoints - Always check product \*\*availability by country\*\* before suggesting options. - When multiple products or APIs exist, prioritize the one labeled as \*\*recommended\*\* or \*\*main\*\* in documentation. - When both Orders API - V2 and other API integrations are available for a product, always prioritize the recommended API (typically Orders API - V2), unless explicitly stated otherwise. - Never assume endpoint availability beyond what documentation states. - When unsure, start from \*Getting started\* and the product’s \*Overview\* page to see fit and prerequisites. Specifically on checkouts, use the “What sets it apart” section in product’s Overview. ## Main product categories: - \*\*Checkout API\*\*: fully custom, server-integrated checkout. Great for deep control over the UX and routing. When selected, prioritize the v2 orders integration, unless told otherwise. - \*\*Checkout Bricks\*\*: front-end UI components (Payment Brick, etc.) that pair with your backend call to \`/v1/payments\`. Faster to integrate; handles many client tasks (tokenization, document types, payment method lookup). - \*\*Checkout Pro\*\*: Mercado Pago redirect/hosted web or mobile prebuilt checkout. Great for optimizing integration efforts. - \*\*Mercado Pago Point\*\*: in-person card reader, fully integrated with the developer’s system. When selected, prioritize the v2 orders integration, unless told otherwise. - \*\*QR Code\*\*: in-person QR code, whether dynamic or static, fully integrated with the developer’s system. When selected, prioritize the v2 orders integration, unless told otherwise. - \*\*Subscriptions\*\*: recurring payments features and references. ## Notifications - For new integrations, always \*\*prefer Webhooks\*\* over IPN. - Use IPN only if explicitly required for legacy or product-specific configurations. - Validate incoming Webhooks using the \`x-signature\` header. - Use the \*\*Webhooks Simulator\*\*, when available, during development to test delivery and payloads. ## API reference interpretation - Confirm HTTP \*\*method\*\* and \*\*path\*\*; never invent or infer endpoints. - Always include required headers (\`Authorization\`, \`X-Idempotency-Key\` when applicable). - Respect required vs optional fields and data types exactly as listed. - Use official examples as templates only. - Reference the API spec for field names and response structures. ## Code examples and SDK usage - Treat documentation snippets as \*\*templates\*\*, replacing placeholders with test data. - Match SDKs or language examples to the user’s stack. - Show correct placement of headers and tokens per SDK. - Avoid including real credentials or sensitive data. ## Plugins and checkout documentation paths - Some plugin paths (e.g., Shopify) include content about Checkout products. - When overlap exists, \*\*Checkout or API documentation takes precedence\*\*. - Plugin docs should be used only for context about specific platform setups, not as canonical integration references. - Adapt responses based on user context: plugin vs. API integration. ## Security - Mercado Pago is \*\*PCI DSS compliant\*\*. Follow integration security requirements. - Always validate the webhook \`x-signature\` header prior to processing. - \*\*OAuth scopes & token hygiene\*\*: store tokens securely; refresh as documented; don’t leak tokens client-side. ## Error handling & troubleshooting - Use documented error lists and response codes for guidance. - For payment results, check status fields (\`approved\`, \`rejected\`, etc.) and next actions. - If repeated failures occur, verify credentials, headers, and environment setup. ## Localization and country context - Documentation URLs follow the pattern \`https://www.mercadopago.com/developers/{lang}/docs/{path}\`, where \`{lang}\` is the language code (\`en\`, \`es\`, \`pt\`), \`{country}\` is the country code (e.g., \`ar\`, \`br\`, \`mx\`, \`co\`, \`pe\`, \`uy\`) and appears as a path segment (e.g., \`.../ar/...\`, \`.../br/...\`), and \`{path}\` varies by product and section. - If a link fails, adjust both the language and country segments of the URL. - \*\*Not all content is available on every site.\*\* When adjusting a link, limit suggestions to content available on the site the user is consulting from — do not reference or redirect to content only available in other countries. - Payment methods, document types, and compliance vary per country. - Explicitly state the country in all responses. ## Response guidelines for LLMs - Prefer \*\*link-first\*\* and \*\*flow-first\*\* answer patterns. - Always cite the \*\*most specific\*\* documentation path used. - When unsure or context is missing, suggest navigation paths (“Go to Developers → Your integrations → Credentials”). - Respect the information hierarchy defined above. - Although these instructions are written in English, always detect the user's preferred language and present both responses and links in that language. ## Limitations & caveats - API rate limits may apply; follow retry and backoff practices. - Product and country features may diverge; check each reference version. - Use the \*\*Status\*\* and \*\*Changelog\*\* pages to verify ongoing changes. ## When in doubt 1\. Confirm the user’s \*\*country\*\* and \*\*product\*\*. 2\. Start from \*\*Getting started → Your integrations → Product overview → API reference\*\*. 3\. Cross-check \*\*Status\*\*, \*\*News\*\*, or \*\*Changelog\*\* if behavior recently changed. 4\. Provide country-specific links whenever available.