` empty and interactive. Never add `disabled`, `readonly`, `pointer-events: none`, or an overlapping decorative element to the host or its iframe. - Give each secure host a non-zero height and `position: relative`; make the injected iframe `display: block`, `width: 100%`, and `height: 100%`. The visible border belongs to the host, not to an overlay. - Mount secure fields only after the new checkout screen route is visible and the host has non-zero dimensions. Use the application's lifecycle/router hook or `requestAnimationFrame`; never initialize into `display: none`, and never use an arbitrary `setTimeout` as the visibility mechanism. - Mount exactly once per visible form instance. In SPAs, unmount/destroy the previous SDK controller or field instances before remounting. - Group each secure host with an external visible label and an accessible relationship, for example: ```html

Validade do cartão (MM/AA)

``` - Only disable the payment submit button while fetching or submitting. Never disable card-data fields as part of loading state management. - In `onFormMounted`, verify that every secure host contains exactly one iframe, has non-zero dimensions, has a visible external label, and that neither host nor iframe resolves to `pointer-events: none`. Surface failures both in the console and in a visible form error; do not report the scaffold as successful. Before continuing, compare the registered field IDs with the rendered IDs in both directions. Then inspect the generated source for `disabled`, `readonly`, `aria-disabled`, `inert`, overlays, and `pointer-events` affecting secure hosts or their ancestors. Missing labels, hidden mounting, duplicated instances, and non-interactive hosts are scaffold failures and must be fixed immediately. Mark every visible field wrapper with `data-mp-field="{fieldName}"`; mark the three SDK iframe hosts with `data-mp-secure-field="cardNumber|expirationDate|securityCode"`; mark the three required CardForm lifecycle selects with `data-mp-sdk-required-field="issuer|installments|identificationType"`. The form must declare whether payer email and identification come from the form or application state using the source markers above. After writing the new screen, run the deterministic acceptance check: ```bash # runtime-endpoint strategy: pass the file that implements the config route node "/scripts/validate-checkout-screen.mjs" "{checkout_screen_file}" "{server_or_config_route_file}" "{cta_file}" # framework-public-config strategy: no server config file is needed node "/scripts/validate-checkout-screen.mjs" "{checkout_screen_file}" "" "{cta_file}" ``` If it fails, fix the new screen and rerun it. Never show a successful scaffold summary until this command exits with code 0. 3.5. **`checkout-pro` and `checkout-api` — Always wire the resolved CTA:** A resolved CTA is mandatory. Preserve the surrounding layout and reuse the project's button classes and accessibility conventions. Mark the final element with `data-mp-checkout-cta="{product}"` so the deterministic check can verify the integration. **When `product=checkout-api`:** preserve the existing CTA's visible text and styling, then replace only its navigation behavior so it opens `{checkout_screen_destination}`. - Existing ``: add `data-mp-checkout-cta="checkout-api"` and set or update `href="{checkout_screen_destination}"`. - Vanilla ` ``` - SPA/framework app: keep one visible project-styled button with `data-mp-checkout-cta="checkout-pro"`; its single handler must call the backend preference route and navigate to the returned `init_point`. Remove the old checkout handler instead of stacking a second listener. - Never create a second checkout page for Checkout Pro. The chosen CTA location is where the Mercado Pago button belongs. **Mandatory verification after editing:** 1. Confirm exactly one final element has `data-mp-checkout-cta="{product}"`. 2. For Checkout API, confirm `{checkout_screen_file}` is separate, `{checkout_screen_destination}` resolves to it, and the CTA has exactly one navigation action to that destination. 3. For Checkout Pro, confirm the visible button says Mercado Pago and reaches the preference-creation route that redirects to `init_point`. 4. Confirm the old CTA handler is gone and clicking cannot trigger two checkout flows. 5. For Checkout API, confirm the payment form's own submit button was not mistaken for or rewired as the entry CTA. 6. Run the deterministic CTA acceptance check and fix any failure before continuing: ```bash node "/scripts/validate-checkout-cta.mjs" "{product}" "{cta_file}" "{checkout_screen_destination_or_preference_route}" ``` For Checkout Pro, also run the server validator. It rejects unconditional `auto_return` when the application has a localhost fallback: ```bash node "/scripts/validate-checkout-pro-server.mjs" "{server_file}" ``` 7. Report `✓ {cta_file}:{cta_line_or_region} → {checkout_screen_destination_or_preference_route}`. There is no successful “CTA not linked” outcome for Checkout Pro or Checkout API. 4. **Create `.env.example`** — write the template vars (MP_ACCESS_TOKEN, MP_PUBLIC_KEY, MP_WEBHOOK_SECRET, APP_URL) to `.env.example`. Only create `.env` with real values if the developer explicitly selected credential import and `get_credentials` succeeded; do not overwrite an existing `.env` without confirmation. Otherwise, never create `.env` — the developer must fill in their own credentials. 5. **Update `.gitignore`** — add `.env`, `.env.*.local`, `.mp-integrate-progress.md` if not already present. 5.5. **Delete `.mp-integrate-progress.md` after successful scaffolding** — this file is only a crash/cancel resume checkpoint. Remove it before running the final product validator and before printing a success summary. Keep it only when the run is canceled, blocked, or failed. Never leave a completed integration with this file present. 6. After all writes, print the product-specific summary. Both successful outcomes must include a wired CTA: **Checkout API:** ``` ✓ npm install mercadopago — OK ✓ {server_file} — Checkout API route added ✓ {checkout_screen_file} — separate checkout screen created ✓ MP_PUBLIC_KEY — loaded through {detected_config_strategy}; no HTML placeholder ✓ {cta_file}:{line} {cta_selector} → {checkout_screen_destination} → {checkout_screen_file} ✓ .env.example — created (fill in your credentials) ✓ .gitignore — updated ``` **Checkout Pro:** ``` ✓ npm install mercadopago — OK ✓ {server_file} — preference route added ✓ {cta_file}:{line} — Pay with Mercado Pago button → {preference_route} ✓ .env.example — created (fill in your credentials) ✓ .gitignore — updated ``` **Scaffold guardrails:** - Never write to files outside the current working directory. - **If credentials were fetched via `get_credentials`:** do not overwrite the confirmed `.env`; only create `.env.example` with placeholders. - **If credentials were not imported:** create `.env.example` with `APP_USR-...` placeholders. Never create `.env` here. - If a target file exists and the developer said "write all", inject code rather than overwrite — show a `+diff`-style preview of what changed. - If any write fails, report the exact error and stop; do not continue to the next file. - **No HTML credential injection:** Do not generate `%MP_PUBLIC_KEY%`, `.replace(...)`, template-token substitution, or an inline hard-coded public key. Use the detected framework's public configuration convention, or a no-store JSON runtime-config endpoint for vanilla/server applications. --- ## Step 5 — Suggest next steps Always close with: 1. **Run `/mp-integrate webhook`** to add the webhook receiver (HMAC validation included). 2. **Run `/mp-integrate test-setup`** to create a test user and load funds. 2.5. **For Orders API products (checkout-api / qr / point — ALL countries):** Ask the user before listing next steps: - Question: *"Orders API requires a test buyer user to process payments. Do you want me to create one now?"* - Options: `"Yes, create test user now"` → invoke `mp-test-setup` skill inline; `"No, I'll do it later"` → show reminder: *"⚠️ Run `/mp-integrate test-setup` before testing — Orders API returns 422 without a test user."* - Note: Card Payment and Payment Bricks use Payments API and do not require the Orders buyer flow. Wallet still needs a buyer logged into Mercado Pago; Status Screen needs an existing payment ID. 3. **Run `/mp-review` — MANDATORY before going to production.** This is **step 6 of 7** in your integration journey. The auto-checker validates your integration automatically after the first payment. Do **not** switch to production credentials (step 7) until `/mp-review` passes. > You are at step 6 of 7. After `/mp-review` passes, the only remaining step is switching to production credentials. --- ## Gotchas Bank Render only the section that matches the chosen product. These are the experiential traps that the docs do not surface clearly. Keep them short. ### checkout-pro - **Always use `init_point`, never `sandbox_init_point`.** Mercado Pago has no sandbox — there is only the production API. Test runs use test-user credentials (`APP_USR-`), not a different URL. - `currency_id` must match the country (ARS, BRL, MXN, CLP, COP, PEN, UYU). - Never trust `back_url` query params alone — always re-fetch payment status server-side. - `auto_return=approved` requires `back_urls.success` set; otherwise it is silently ignored. - `external_reference` is your reconciliation anchor — set it on every preference/order. ### checkout-api - **⛔ Orders API requires a test user buyer** — `422 unprocessable_content` if you use an arbitrary email. Run `/mp-integrate test-setup` **before** testing. This applies to ALL countries. - **`getCardFormData()` returns camelCase** — `paymentMethodId` and `issuerId`, not `payment_method_id` and `issuer_id`. Map them on the server. - **`issuer_id` is NOT allowed inside `payment_method`** for Orders API — remove it from the payload or you get `additionalProperties not allowed`. - **Minimal Checkout API UI** — always show card number, expiration, security code, and cardholder name. Collect payer email/identification only when trusted application state does not already provide them. Keep the SDK-required `issuer`, `installments`, and `identificationType` selects in the DOM/CardForm map but hidden from the minimal UI; enforce `installments: 1` server-side unless the merchant explicitly offers installments. - **`total_amount` and `amount` must be `"10.00"` not `"10"`** — use `Number(x).toFixed(2)`. - **Brazil (MLB)**: this product is called **Checkout Transparente** — use that name in MCP queries. - Card tokens are single-use and expire in 7 days. - Always send an idempotency key on payment creation; retries without it create duplicate charges. ### bricks - **The backend is variant-specific.** `card-payment` and `payment` create via Payments API; `wallet` creates a dynamic preference at `/checkout/preferences` (without `v1`); `status-screen` only displays an existing `paymentId`. - **Always show the charge amount above the brick.** The brick does not render the total prominently — buyers cannot see what they're paying. Add `

Total: {currency} {amount}

` above the container div. - **Always include three payment states in your UI.** (1) Loading/spinner while the brick initializes and while `onSubmit` runs. (2) Success state showing payment ID and "Payment approved" message. (3) Error state with an actionable message ("Card declined — try a different card"), not the raw API error string. Missing these states means buyers don't know if the payment went through. - The container `

` must exist in the DOM **before** calling `bricksBuilder.create(...)`. A `setTimeout` is not a fix; use `onReady` or React `useEffect` with the ref mounted. - `onSubmit` must return a **Promise** that resolves after the server responds — returning `void` makes the brick stay in the loading state forever. - For Card Payment Brick: amount validation happens server-side; never trust the amount echoed by the brick. - Wallet Brick requires the buyer to be logged into Mercado Pago — test users count as logged in if you use their credentials. - Status Screen Brick handles 3DS challenge rendering; do not also render your own 3DS iframe. - **Ad-blockers (uBlock, AdBlock Plus, Brave shields) block `sdk.mercadopago.com`** → the brick raises `FIELDS_SETUP_FAILED` and silently fails to mount. If a developer reports "the brick doesn't appear", check the ad-blocker before debugging code. - **Debit cards do NOT show an installments selector** — this is correct behavior, not a bug. Make sure the server accepts `installments: 1` for debit and does not require the selector field to be present. - **Never hardcode `preferenceId` as a placeholder** (e.g., ``, `YOUR_PREFERENCE_ID`, `"preference_id"`): the brick fails silently. The `preferenceId` must always be created dynamically on the server per buyer session. - **Never trust Wallet item prices from the browser.** Send an opaque cart/purchase ID and rebuild the preference items and amount from trusted server-side state before calling Mercado Pago. - **Preferences never use a version prefix or segment.** The valid path is exactly `/checkout/preferences`. - **Status Screen Brick needs a `payment_id`** — extract it from the `POST /v1/payments` response (`response.id`) and pass it to the brick. Do not pass an order ID. - **Vanilla builder lifecycle:** retain the controller returned by `bricksBuilder.create()` and call `controller.unmount()` before rebuilding or removing its container. The React SDK component owns its own controller lifecycle; do not create a second controller around it. - **`back_urls` must be on the same origin as the page that mounts the brick.** Cross-domain back_urls fail silently — the redirect after payment lands on a blank page with no error. ### qr - New integrations always use Orders API with `type: "qr"`; legacy `/instore/...` routes and QR-encoded Checkout redirect URLs are scaffold failures. - Store + POS must exist before the order. `config.qr.external_pos_id` must exactly match the POS `external_id` and belong to the seller whose token creates the order. - Valid modes are `static`, `dynamic`, and `hybrid`. Only dynamic and hybrid return `type_response.qr_data`; static uses the QR returned by POS creation. - Encode QR data locally and never send it to a third-party image generator. Poll the order and handle `created`, `processed`, `canceled`, `expired`, and `refunded` explicitly. - QR Orders webhooks use the `orders` topic. A real processed/refund test still requires scanning with the buyer test account; do not invent the Point `/events` simulator for QR. ### point - New integrations use Orders API with `type: "point"` and `config.point.terminal_id`; never scaffold `/point/integration-api/.../payment-intents`, `type: "instore"`, or `config.device.id`. - Without physical hardware, use the standard virtual terminal `NEWLAND_N950__SBX0000001` only behind explicit test mode and simulate each order result through `/v1/orders/{order_id}/events`. It is not valid for integration-quality measurement. - A physical device must be paired to a User ID (not the application) and run in PDV mode. A device paired to the wrong user will silently reject orders. - After a firmware update the device may take ~2 minutes to come back online; do not retry order creation aggressively. - Webhook topic for Point (Orders API) is `orders`. The legacy `point_integration_wh` topic belongs to the old Point Integration API — do not use it for new integrations. ### subscriptions - Pick `with-plan`, `without-plan-authorized`, or `without-plan-pending` before scaffolding. A preapproval created without a plan cannot be migrated to one later. - Never expose a manual card-token field. Authorized contracts require secure MercadoPago.js tokenization; pending omits the token and redirects to `init_point`. - Associated plan IDs and all recurrence terms are server-controlled. Never accept plan ID, amount, currency, or frequency from the browser. - Recurring charges retry on failure; support `authorized`, `pending`, `paused`, and `canceled` explicitly and reconcile through GET/webhooks. - The `back_url` must be HTTPS in production; HTTP is only acceptable for a local-development fallback. ### marketplace - Marketplace is OAuth plus a checkout contract, not a standalone Orders API. Resolve Checkout Pro, Checkout API/Payments, or Wallet Brick first. - Use a cryptographic one-time OAuth `state`, the exact configured redirect URI, encrypted persistent tokens, and atomic refresh-token rotation. Never expose or log seller tokens. - Resolve seller, cart amount, and commission from trusted server state. Never accept `seller_id`, `collector_id`, amount, or fee from the buyer request. - Checkout Pro/Wallet use `marketplace_fee` on `/checkout/preferences`; Checkout API uses `application_fee` on `/v1/payments`. The seller OAuth token in the Authorization header determines the receiving seller; do not invent `collector_id` in the payment payload. ### wallet-connect - **Requires commercial enablement by Mercado Pago.** If it is not explicitly active, stop before changing project files. - The user must approve the linkage in MP wallet UI — there is no silent linking. - Create a dedicated account-linking page and wire the application's real final checkout CTA to it when one exists. - The approval code and payer token are server-only. Encrypt the payer token in persistent storage and never expose it to the browser or logs. - Once linked, payments use the buyer's saved methods through Orders API — do not pass card details, load MercadoPago.js, or substitute the Wallet Brick. - Use a unique idempotency key, trusted purchase data, and matching two-decimal order/payment amounts. ### money-out - The current product name is **Payouts**. Never scaffold the obsolete generic `disbursements` contract or substitute Advanced Payments. - The API contract is country-specific: resolve it before generating code and never reuse Argentina payloads for Brazil or vice versa. - Payouts is a privileged server-side money-movement operation. Require operator authorization, trusted durable instructions, persisted idempotency, and an audit trail; never trust destination or amount from a browser. - Test calls require explicit Payouts test mode and the official test header. Production requires Ed25519 signing of the exact serialized body. - Accepted, created, and pending are not final accreditation. Reconcile the returned resource by lookup and Webhooks. ### smartapps - **Requires direct contact with the Mercado Pago team** — SmartApps is not self-service. Do not scaffold without confirming the developer has an active agreement with MP. - SmartApps run on Point devices — code limits and APIs differ from server SDKs. Always query MCP for the SmartApps-specific guide. - Never retrofit a web application as a SmartApp. The target must be Android; create a separate Android app/module only after the developer authorizes that scope. - The SDK is a private AAR from the Mercado Pago integration kit. Ask before updating it, use only the latest artifact confirmed by the integration team, and never substitute a public SDK coordinate. - A static validator cannot replace compilation with the real AAR, sandbox mock tests on a development terminal, or Mercado Pago homologation. --- ## What this skill does NOT do - It does **not** validate webhooks. Use the `mp-webhooks` skill (or `/mp-integrate webhook`). - It does **not** create test users. Use the `mp-test-setup` skill (or `/mp-integrate test-setup`). - It does **not** evaluate integration quality. Use the `mp-review` skill (or `/mp-review`). - It does **not** invent code from memory. Snippets come from the WebFetched official `llms.txt` per country (tier 1), `references/products.md` (tier 2), or MCP `search_documentation` (tier 3 fallback). Never from training-data memory alone.

Payment approved!