# 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), Subscriptions, Plugins and Platforms. 

- **API Reference**: canonical definitions for endpoints (e.g., `/v1/payments`, `/oauth/token`, `/v1/identification_types`). 

- **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 official integration support.

## Authentication & credentials 

- **Server-side**: use the **Access Token** (private credential) in `Authorization: Bearer <ACCESS_TOKEN>`. 

- **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. 

- Simulate user roles and transactions with **test users** when applicable.

## 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 **Payments API** integrations are available for a product, **explicitly present both integration options** and allow the user to choose, unless an explicit exception is provided in the documentation. 

- 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 for checkouts, use the “What sets it apart” section in the product’s Overview.

## Main product categories 

- **Checkout API**: fully custom, server-integrated checkout. Suitable for deep control over UX and routing. When selected, clearly present both Orders API - V2 and Payments API integration paths and let the user decide which to use. 

- **Checkout Bricks**: front-end UI components (Payment Brick, etc.) that pair with your backend call to `/v1/payments`. Faster to integrate; handles client-side tasks such as tokenization, document types, and payment method lookup. 

- **Checkout Pro**: Mercado Pago hosted redirect checkout (web or mobile). Optimized for faster integration with prebuilt flows. 

- **Subscriptions**: recurring payments features and related endpoints.

## 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 specification for field names and response structures.

## Code examples and SDK usage 

- Treat documentation snippets as **templates**, replacing placeholders with test data. 

- Match SDK 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 documentation should be used only for context about specific platform setups, not as canonical integration references. 

- Adapt responses based on user context: plugin vs. direct 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, and never expose 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 configuration.

## 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 requirements 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 context is missing, suggest navigation paths (e.g., “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 best 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.

# Mercado Pago API Reference

> API Reference for Mercado Pago payment solutions

## OAuth

- [Create and refresh token](https://beta.mercadopago.com.pe/developers/en/reference/authentication/oauth/_oauth_token/post): Create and refresh token

## Checkout Pro

- Preferences: Preferences
  - [Create preference](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/preferences/create-preference/post): Create preference
  - [Search preferences](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/preferences/search-preferences/get): Search preferences
  - [Get preference](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/preferences/get-preference/get): Get preference
  - [Update preference](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/preferences/update-preference/put): Update preference
- Payments: Payments
  - [Search payments](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/search-payments/get): Search payments
  - [Get payment](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/get-payment/get): Get payment
- Merchant orders: Merchant orders
  - [Search merchant orders](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/merchant_orders/search-merchant-order/get): Search merchant orders
  - [Get merchant order](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/merchant_orders/get-merchant-order/get): Get merchant order
  - [Update merchant order](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/merchant_orders/update-merchant-order/put): Update merchant order
- Payment methods: Payment methods
  - [Get payment methods](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/payment_methods/get): Get payment methods
- Cancellations: Cancellations
  - [Create cancellation](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/create-cancellation/put): Create cancellation
- Refunds: Refunds
  - [Create refund](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/create-refund/post): Create refund
  - [Get refunds list](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/get-refunds/get): Get refunds list
  - [Get specific refund](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/get-refund/get): Get specific refund
- Chargebacks: Chargebacks
  - [Get chargeback](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-pro/chargebacks/get): Get chargeback

## Checkout API

- Orders API: Orders API
  - Orders: Orders
    - [Create order](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/create-order/post): Create order
    - [Capture order fully](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/capture-order/post): Capture order fully
    - [Add transactions to the order](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/add-transaction-order/post): Add transactions to the order
    - [Delete a transaction from the order](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/delete-transaction-order/delete): Delete a transaction from the order
    - [Update a transaction from the order](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/update-transaction-order/put): Update a transaction from the order
    - [Process order by ID](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/process-order/post): Process order by ID
    - [Search order](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/search-order/get): Search order.
    - [Get order by ID](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/get-order/get): Get order by ID
    - [Cancel order by ID](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/cancel-order/post): Cancel order by ID
    - [Refund order](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/refund-order/post): Refund order
  - Payment methods: Payment methods
    - [Get payment methods](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/payment-methods/get): Get payment methods
  - Document types: Document types
    - [Get document types](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/identification-types/get): Get document types
  - Cards: Cards
    - [Save card](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/cards/save-card/post): Save card
    - [Get customer cards](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/cards/get-customer-cards/get): Get customer cards
    - [Get card](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/cards/get-card/get): Get card
    - [Update card](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/cards/update-card/put): Update card
    - [Delete card](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/cards/delete-card/delete): Delete card
  - Customers: Customers
    - [Create customer](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/customers/create-customer/post): Create customer
    - [Search customers](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/customers/search-customer/get): Search customers
    - [Get customer](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/customers/get-customer/get): Get customer
    - [Update customer](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/customers/update-customer/put): Update customer
  - Addresses: Addresses
  - Chargebacks: Chargebacks
    - [Get chargeback](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api/get-chargeback/get): Get chargeback
- Payments API: Payments API
  - Payments: Payments
    - [Create payment](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/create-payment/post): Create payment
    - [Search payments](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/search-payments/get): Search payments
    - [Get payment](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/get-payment/get): Get payment
    - [Update payment](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/update-payment/put): Update payment
  - Customers: Customers
    - [Create customer](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/customers/create-customer/post): Create customer
    - [Search customers](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/customers/search-customer/get): Search customers
    - [Get customer](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/customers/get-customer/get): Get customer
    - [Update customer](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/customers/update-customer/put): Update customer
  - Cards: Cards
    - [Save card](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/cards/save-card/post): Save card
    - [Get customer cards](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/cards/get-customer-cards/get): Get customer cards
    - [Get card](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/cards/get-card/get): Get card
    - [Update card](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/cards/update-card/put): Update card
    - [Delete card](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/cards/delete-card/delete): Delete card
  - Addresses: Addresses
  - Payment methods: Payment methods
    - [Get payment methods](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/payment-methods/get): Get payment methods
  - Document types: Document types
    - [Get document types](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/identification-types/get): Get document types
  - Cancellations: Cancellations
    - [Create cancellation](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/create-cancellation/put): Create cancellation
  - Refunds: Refunds
    - [Create refund](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/create-refund/post): Create refund
    - [Get specific refund](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/get-refund/get): Get specific refund
    - [Get refunds list](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/get-refunds/get): Get refunds list
  - Chargebacks: Chargebacks
    - [Get chargeback](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/checkout-api-payments/get-chargeback/get): Get chargeback

## Subscriptions

- Subscriptions: Subscriptions
  - [Create subscription](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/create-preapproval/post): Create subscription
  - [Search in subscriptions](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/search-preapproval/get): Description
  - [Get subscription](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/get-preapproval/get): Get subscription
  - [Update subscription ](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/update-preapproval/put): Update subscription
  - [Export subscriptions](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/export-preapproval/get): Export subscriptions
- Plans: Plans
  - [Create subscription plan](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/create-preapproval-plan/post): Create subscription plan
  - [Search in subscription plan](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/search-preapproval-plan/get): Search in subscription plan
  - [Get subscription plan](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/get-preapproval-plan/get): Get subscription plan
  - [Update subscription plan](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/update-preapproval-plan/put): Update subscription plan
- Invoices: Invoices
  - [Get invoice data](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/get-authorized-payment/get): Get invoice data
  - [Search in invoices](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/authorized-payment-search/get): Search in invoices
- Payments: Payments
  - [Search payments](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/search-payments/get): Search payments
  - [Get payment](https://beta.mercadopago.com.pe/developers/en/reference/online-payments/subscriptions/get-payment/get): Get payment

## Claims

- Claims: Claims
  - [Get claim details](https://beta.mercadopago.com.pe/developers/en/reference/claims/get-claim-details/get): Get claim details
  - [Search claims](https://beta.mercadopago.com.pe/developers/en/reference/claims/search-claims/get): Search claims
  - [Get the reason for the claim](https://beta.mercadopago.com.pe/developers/en/reference/claims/get-reason-for-claim/get): Get the reason for the claim
  - [Get claim history](https://beta.mercadopago.com.pe/developers/en/reference/claims/get-claim-history/get): Get claim history
  - [Get claim evidence](https://beta.mercadopago.com.pe/developers/en/reference/claims/get-claim-evidence/get): Get claim evidence
  - [Get claim notifications](https://beta.mercadopago.com.pe/developers/en/reference/claims/get-claim-notifications/get): Get claim notifications
- Files and messages: Files and messages
  - [Get claim messages](https://beta.mercadopago.com.pe/developers/en/reference/claims/get-claim-messages/get): Get claim messages
  - [Get file data](https://beta.mercadopago.com.pe/developers/en/reference/claims/get-file-data/get): Get file data
  - [Download attached files](https://beta.mercadopago.com.pe/developers/en/reference/claims/download-attached-files/get): Download attached files
  - [Attach files to the message](https://beta.mercadopago.com.pe/developers/en/reference/claims/attach-files-to-message/post): Attach files to the message
  - [Send message with file](https://beta.mercadopago.com.pe/developers/en/reference/claims/send-message-with-file/post): Send message with file
- Resolutions: Resolutions
  - [Request claim mediation](https://beta.mercadopago.com.pe/developers/en/reference/claims/request-mediation-claim/post): Request claim mediation
  - [See expected resolutions at mediation](https://beta.mercadopago.com.pe/developers/en/reference/claims/see-expected-resolutions-mediation/get): See expected resolutions at mediation
- Delivery: Delivery
  - [Upload shipping evidence](https://beta.mercadopago.com.pe/developers/en/reference/claims/upload-shipping-evidence/post): Upload shipping evidence

## Reports

- Releases
  - [Create new configuration](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/create-new-configuration/post)
  - [Update configurations](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/update-configurations/put)
  - [Consult configurations](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/consult-configurations/get)
  - [Get report generation task](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/search-task/get): Get report generation task
  - [Create report](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/create-report/post)
  - [Consult report list](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/consult-report/get)
  - [Search specific report](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/search-report/get): Search specific report
  - [Enable automatic generation](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/enable-automatic-generation/post)
  - [Disable automatic generation](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/disable-automatic-generation/delete)
  - [Download report](https://beta.mercadopago.com.pe/developers/en/reference/releases-report/download-report/get)
- Account money
  - [Create a new configuration](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/create-new-configuration/post): Create a new configuration
  - [Update configurations](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/update-configurations/put): Update configurations
  - [Query configurations](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/query-configurations/get): Query configurations
  - [Create report](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/create-report/post): Create report
  - [Query report generation task](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/query-task-status/get): Query report generation task
  - [Query reports list](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/query-report/get): Query reports
  - [Search specific report](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/search-report/get): Search report
  - [Enable automatic generation](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/enable-automatic-generation/post): Enable automatic generation
  - [Disable automatic generation](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/disable-automatic-generation/delete): Disable automatic generation
  - [Download report](https://beta.mercadopago.com.pe/developers/en/reference/settlements-report/download-report/get): Download report