mp-integrate

mp-integrate

此技能是构建 Mercado Pago 集成的唯一入口。它会收集开发者所需的最少上下文，并使用经过筛选的参考文件组装一份可直接粘贴的内容包；必要时则使用 MCP 服务作为后备方案。

参考文件 — 生成任何代码之前必须先阅读

所有打包的参考文件和脚本都使用 ${CLAUDE_PLUGIN_ROOT}。Claude Code 会将其解析为当前启用的插件版本。切勿扫描安装缓存、加载其他市场中的副本，或将插件的 .mcp.json 复制到开发者的项目中。

文件	绝对路径	阅读时机
terminology-rules.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/terminology-rules.md	始终最先阅读
recommendation-template.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/recommendation-template.md	始终阅读 — 必须遵循的输出结构
guides/checkout-pro.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/checkout-pro.md	product = checkout-pro
guides/checkout-api.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/checkout-api.md	product = checkout-api
guides/bricks.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/bricks.md	product = bricks
guides/qr.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/qr.md	product = qr
guides/point.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/point.md	product = point
guides/subscriptions.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/subscriptions.md	product = subscriptions
guides/marketplace.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/marketplace.md	product = marketplace
guides/wallet-connect.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/wallet-connect.md	product = wallet-connect
guides/payouts.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/payouts.md	product = money-out（当前名称：Payouts）
guides/smartapps.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/smartapps.md	product = smartapps
guides/webhooks.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/webhooks.md	任意 product + webhooks
products.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/products.md	各国家的测试卡、API 参考

阅读完上述所有适用文件之前，不得使用 MCP。 如需查阅最新文档，请使用 WebFetch 获取官方 {country_domain}/developers/llms.txt（第 1 层 — 见步骤 3）；若无法获取，则使用 products.md。

---

⚠️ 重要 — 通过 /mp-integrate 命令调用时： 命令文件已运行环境检查和就绪流程。请直接从步骤 1.a 开始（自动检测 SDK/客户端/模式）。不要检查 MCP 状态。只有开发者明确选择使用 MCP 的选项时，才导入凭据。

---

⚠️ 强制约束 — 开始任何操作之前先阅读

这些规则优先于向导执行过程中的任何“合理判断”。以往的向导运行曾违反这些规则；请勿重蹈覆辙。

LOCK 1 — SDK 绝不是向导问题

绝不会通过 AskUserQuestion 询问 SDK／语言。就这样。

• 在步骤 1.a 中，通过 glob 搜索仓库中的清单文件（package.json、pyproject.toml 等），静默确定 SDK。
• 如果找到一个清单文件 → 记录 SDK 并完全跳过该问题。
• 如果找到多个清单文件（真正的多语言单体仓库）→ 仍然不要询问。选择与开发者当前正在编辑的目录相匹配的清单，或者默认为 node。在聊天中用一行说明选择（✓ SDK: node — from package.json），然后继续，不要询问。
• 如果完全找不到清单文件 → 仍然不要询问。默认为 node，并说明这一点（✓ SDK: node — defaulted (no manifest detected; we'll create package.json during scaffolding)），然后继续。
• 确定该技术栈对应的官方软件包，并查询其官方软件包注册表，获取当前稳定版。“稳定版”指注册表中的默认／最新版本，不包括 alpha、beta、候选发布版、nightly 或预览版。
• 将已安装版本与该稳定版进行比较。在安装或更新之前，展示软件包、当前版本（或“未安装”）、建议版本，以及将要更改的清单文件／锁定文件，然后通过 AskUserQuestion 请求明确授权。
• 如果获准，则安装或更新到当前稳定版，调整受不兼容变更影响的代码，更新锁定文件，并运行相关测试。如果未获准，则不要更改依赖项；如果集成所需的 SDK 缺失或过时，也不要报告该集成已就绪。

如果你发现自己正准备调用 AskUserQuestion，且 header="SDK"、header="Stack" 或 header="Language"，请立即停止。SDK 不是供用户选择的选项。向导顶部的 Tabs 行不得包含“SDK”标签。

LOCK 2 — 产品 → 模式可用性表（不可妥协）

产品	唯一有效的 mode 值	选择器行为
checkout-pro	preferences（Checkout Pro 没有 Orders API）	完全跳过模式问题。 不要调用 AskUserQuestion 并设置 header="Mode"。不要将“Orders API”显示为选项。静默使用 mode=preferences。
checkout-api	orders	所有国家/地区始终使用 orders。
bricks	payments	内部路由值。card-payment 和 payment 会创建 Payments API 支付；wallet 会创建 /checkout/preferences；status-screen 只显示一个 paymentId。绝不要在 preferences 路径中添加 v1。
qr	orders	所有国家/地区始终使用 orders。
point	orders	所有国家/地区始终使用 orders。
marketplace	preferences 或 payments	先解析 marketplace-checkout=。Checkout Pro 和 Wallet Brick 使用 Preferences；Checkout API 使用 Payments API。Marketplace 不是独立的 Orders API 模式。
wallet-connect	orders	始终使用 orders。绝不要询问。
subscriptions	n/a（使用自己的 preapproval API）	跳过模式问题。
money-out	n/a（当前产品名称：Payouts；API 契约因国家/地区而异）	跳过模式问题。
smartapps	n/a	跳过模式问题。

如果 product=checkout-pro，而你正准备显示包含 Orders API 的模式选择器，请中止操作。 Checkout Pro 目前不支持 Orders API。就这样。不要为了“面向未来”而提供此选项。不要为其添加“Recommended”标签。不要将其放入任何“Other”备用选项中。

LOCK 3 — 始终使用 init_point，绝不使用 sandbox_init_point

Mercado Pago 已移除沙盒环境。没有暂存 URL。所有集成（包括测试用户流程）都使用生产 API。

绝不生成引用 sandbox_init_point 的代码。 始终使用偏好设置响应中的 init_point。测试运行和生产运行的区别仅在于加载的凭据不同（来自测试用户的 APP_USR- 与真实账户的凭据），而不在于 URL。

如果在现有代码中发现 sandbox_init_point，请将其标记为错误：重定向会静默失败，或跳转到错误页面。

同样适用于测试用户： 通过 create_test_user 创建的测试用户使用为该测试用户账户返回的 APP_USR- 凭据，连接生产 API 主机。不存在单独的测试基础 URL 或沙盒开关。这并不意味着 TEST- 凭据无效：Checkout API、Bricks 和 Payments API 的静态测试凭据可以使用 TEST-。使用任何凭据的代码都无法通过 sandbox_init_point 正常运行。

LOCK 4 — 选项卡行必须只显示实际会询问的问题

向导顶部的选项卡行（□ Country □ Product □ Mode ✓ Submit）必须只包含根据 LOCK 1 和 LOCK 2 确实仍未确定且未跳过的维度。具体而言：

• 选项卡中绝不能包含“SDK”——参见 LOCK 1。
• 当 product 为 checkout-pro / bricks / wallet-connect / subscriptions / money-out / smartapps 时，选项卡中绝不能包含“Mode”。
• 选项卡中绝不能包含“Environment”。

LOCK 5 — Checkout CTA 对 Pro 和 API 都是必需的

确定产品后，立即在进入任何产品分支前规范化以下别名：

• checkout-api-orders、checkout-transparente、checkout-transparent、checkout_api → checkout-api
• checkout-pro 保持为 checkout-pro

对于规范化后的任一值，在组装或编写结账 UI 之前，从目标项目根目录运行以下命令：

node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-checkout-cta.mjs" "{product}" .

保存返回的 product、status、selected、candidates 和 nextAction，供第 2.5 步使用。不要自行将 checkout-api-orders 解释为其他产品。nextAction=wire_selected_cta 要求使用 selected；nextAction=ask_user_for_cta_or_insertion_location 要求立即调用 AskUserQuestion，询问具体目标。Checkout Pro 或 Checkout API 脚手架在未接入 CTA 的情况下绝不能成功完成。此锁同样适用于这两种产品；修复 Checkout API 时，不要更改 Checkout Pro 的现有行为。

LOCK 6 — Checkout Pro 的本地返回 URL 绝不能启用 auto_return

当 product=checkout-pro 时，只有有效的 APP_URL 为公开的 HTTPS 源站，auto_return: "approved" 才有效。如果 APP_URL 缺失、使用 localhost、127.0.0.1、0.0.0.0 或不是 HTTPS，则从偏好设置请求体中省略 auto_return。不要只提供 localhost back_urls：Preferences API 会在创建偏好设置之前拒绝这种组合。

对于同时支持本地和生产环境运行的应用，根据 APP_URL 派生一个显式的 publicAppUrl 布尔值（HTTPS 且非本地），并仅在其为 true 时有条件地展开 { auto_return: "approved" }。报告成功之前，必须按照第 3.5 步的要求运行 validate-checkout-pro-server.mjs。

LOCK 7 — Point 使用 Orders API，并支持无硬件测试模式

当 product=point 时，仅搭建当前 Orders API 流程：POST /v1/orders、type: "point" 和 config.point.terminal_id。绝不生成 /point/integration-api/.../payment-intents、type: "instore" 或 config.device.id。

对于没有硬件的开发者，支持官方标准虚拟终端 NEWLAND_N950__SBX0000001，但必须仅在显式启用 MP_POINT_TEST_MODE=true 的情况下使用。生产环境必须要求提供 MP_POINT_TERMINAL_ID；绝不能静默回退到虚拟终端。加入按 ID 查询订单的功能，以便应用协调异步状态变更。报告成功前，运行：

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-point-server.mjs" "{server_file}"

LOCK 8 — QR 使用 Orders API，并要求已有 Store 和 POS

当 product=qr 时，仅搭建 POST /v1/orders，并设置 type: "qr"、匹配的 total_amount 和 transactions.payments[0].amount，以及 config.qr.external_pos_id。QR 仅支持 static、dynamic 和 hybrid 三种有效模式。绝不生成 /instore/orders/qr/...、/instore/qr/...、重定向式 Checkout 订单，或内容为 Checkout URL 的 QR。保持请求精简： 不要擅自添加 payer，并移除旧版的 items[].currency_id 和 items[].total_amount 字段。验证客户端提供的价格、数量和计算得出的总额均为有限正数。QR 取消操作不得复制仅适用于 Point 的 X-Allow-Cancelable-Status 标头。

创建 Store 和 POS 是前置条件，而不是搭建过程中的隐式副作用。如果明确配置了现有 POS，则重复使用。如果没有可用的 POS，则在创建持久化资源之前，询问真实的 Store 地址；绝不编造地址。Dynamic 和 hybrid 模式在本地呈现 type_response.qr_data。Static 模式则呈现创建 POS 时返回的 QR。加入订单查询和取消功能，并在报告成功前运行两项验收检查：

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-qr-server.mjs" "{server_file}"
node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-qr-client.mjs" "{client_file}" 'data-mp-qr-cta="create-order"' "/api/qr/orders"

LOCK 9 — Bricks 的行为因变体而异

编写代码前解析 brick=，并阅读 references/guides/bricks.md。绝不要将一个 Brick 的后端用于全部四种变体：

• card-payment：CardPayment/cardPayment 创建 Payments API 支付。
• payment：Payment/payment 通过 Payments API 使用所选方式创建支付。
• wallet：Wallet/wallet 严格通过 /checkout/preferences 创建偏好设置；该路径不包含版本段。
• status-screen：StatusScreen/statusScreen 呈现经过验证的 paymentId； 它不会创建支付，且不得接收订单 ID。

使用应用实际采用的框架，并扫描整个项目，查找真实的结账 CTA。如果存在，则保留其呈现方式，并在移除相互冲突的旧处理程序后，将其链接到新的专用 Brick 页面。如果不存在，仍要创建该页面，并报告开发者必须链接的确切路由/调用方式。绝不要在 Brick 周围收集原始卡号字段。报告成功前：

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bricks-integration.mjs" . "{brick}"

LOCK 10 — 订阅合约不得混用

当 product=subscriptions 时，请先确定 subscription-model=，再编写代码， 并阅读 references/guides/subscriptions.md。唯一有效的值为 with-plan、without-plan-authorized 和 without-plan-pending。

• with-plan 使用由服务端控制的 preapproval_plan_id、经过安全令牌化的 card_token_id，以及 status: "authorized"。绝不接受来自浏览器的计划 ID， 也不要根据买家 CTA 创建计划。
• without-plan-authorized 发送可信的服务端周期条款、经过安全令牌化的 card_token_id，以及 status: "authorized"。
• without-plan-pending 发送可信的周期条款和 status: "pending"， 不包含 card_token_id，并且只重定向到返回的 init_point。

已授权流程必须使用 MercadoPago.js CardForm 或官方 Card Payment Brick。绝不要求买家粘贴卡片令牌，绝不收集原始卡片数据，也绝不省略 CardForm 生命周期选择项（issuer、installments 和 identificationType）。扫描整个应用中的每个订阅 CTA。所有营销/入口 CTA 都必须汇聚到现有或新生成的专用注册页面；只有该页面的最终 CTA 才能创建预审批。 移除相互竞争的演示处理程序和孤立的服务端路由，确保只保留一个预审批创建器。 报告成功之前：

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-subscriptions-integration.mjs" . "{subscription-model}"

LOCK 11 — Marketplace 使用 OAuth + 一种受支持的结账方式

当 product=marketplace 时，请先确定 marketplace-checkout=，再编写代码， 并阅读 references/guides/marketplace.md。唯一支持的值为 checkout-pro、checkout-api 和 bricks-wallet。

• checkout-pro 使用已连接卖家的 OAuth 访问令牌、且只能使用 /checkout/preferences，以及 marketplace_fee。
• checkout-api 使用集成方公钥、已连接卖家的 OAuth 访问令牌、/v1/payments、安全令牌化，以及 application_fee。
• bricks-wallet 使用集成方公钥、卖家 OAuth 访问令牌、且只能使用 /checkout/preferences、marketplace_fee、动态 preferenceId，以及 marketplace: true。

每种合约都必须实现一次性服务端 OAuth 状态、精确匹配重定向 URI、 授权码交换、加密并持久化的卖家令牌、刷新令牌轮换，以及可信的服务端卖家/购物车/佣金 解析。绝不接受来自浏览器的卖家 ID、金额、佣金、收款方 ID 或 OAuth 令牌。Marketplace 不是独立的 Orders API 流程，也不得静默回退到平台令牌。 报告成功之前：

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace-integration.mjs" . "{marketplace-checkout}"

LOCK 12 — Wallet Connect 需要商业权限和仅限服务端的关联

当 product=wallet-connect 时，做出任何脚手架决策前，请先阅读 references/guides/wallet-connect.md。

1. 确认 Mercado Pago 已为开发者的应用启用 Wallet Connect 商业权限。如果开发者明确表示尚未启用，请停止，返回 BLOCKED: active Wallet Connect agreement required，且不要写入文件。如果启用状态未知，请在写入前询问一次。
2. 始终使用固定的 orders 模式。不要询问模式，也不要用 Wallet Brick 或 Advanced Payments API 替代此产品。
3. 创建专用的账户关联／支付页面，并扫描整个项目以查找实际的最终结账 CTA。找到后，请保留并接入该 CTA；否则，请报告开发者必须关联的确切新路由和调用方式。
4. 账户关联、审批码交换、付款方令牌创建、加密、持久化以及 Orders API 支付创建都必须在服务端完成。浏览器只能接收安全的关联状态、审批重定向 URI 和最终订单状态／ID。
5. 从已通过身份验证的服务端状态推导买家身份和购买金额。绝不能将外部用户身份、付款方令牌、金额或已存储凭证语义作为权威的浏览器输入。
6. 不要加载 MercadoPago.js，不要索取公钥，不要挂载 Wallet Brick，也不要渲染卡片字段。买家审批在 Mercado Pago 钱包界面中完成。

报告成功前，请运行：

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-wallet-connect-integration.mjs" .

LOCK 13 — SmartApps 需要商业权限、Android 和其私有 SDK

当 product=smartapps 时，做出任何脚手架决策前，请先阅读 references/guides/smartapps.md。

1. 确认开发者已与 Mercado Pago 团队签订有效的 SmartApps 协议。如果未明确确认，请停止，返回 BLOCKED: active SmartApps agreement required，且不要写入文件。
2. 即使已有第 1 层级公开文档，也要通过 mcp__plugin_mercadopago_mcp__search_documentation 查询当前的 SmartApps 指南。如果缺少 MCP 身份验证，请运行常规的内联身份验证流程，并在成功前停止。
3. 必须指定 Android 目标。绝不要将 SmartApps 转换为或嵌入 Web、后端、桌面或 iOS 应用。如果代码库没有 Android 应用，请说明需要单独的 Android 应用／模块，并在扩大范围前询问。
4. 写入前，先确定是 main 还是 mini，以及是 own 还是 third-party。主应用拥有 HOME 启动器；迷你应用则不拥有。第三方集成需要使用 SDK OAuth 模式。
5. SDK 是 Mercado Pago 集成套件中提供的私有 AAR。绝不要用公开的 Mercado Pago SDK 替代，也不要臆造 Maven 坐标。复制／更新前请先询问，向集成团队确认最新构件，并且只使用最新版本。
6. 支付方式、支付、打印机、扫描仪／摄像头和 Bluetooth 都通过 SmartApps SDK 使用。不要从终端直接调用支付 API，也不要请求被禁止的 Android 权限。

报告静态脚手架成功前，请运行：

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-smartapps-integration.mjs" . "{main|mini}" "{own|third-party}"

通过此检查并不代表设备认证。编译需要实际的最新 AAR；支付和硬件验证需要 Mercado Pago 开发终端和 sandbox 风味的套件。

LOCK 14 — Money Out 即 Payouts，且其契约因国家而异

当 product=money-out 时，在做出任何脚手架决策前，先阅读 references/guides/payouts.md，并将当前产品名称显示为 Payouts。

1. 绝不搭建 disbursements API、Advanced Payments、Marketplace 分账、 结账流程、买家 CTA 或银行卡表单。旧的 Money Out URL 现在会重定向到 Payouts。
2. 编写前，先根据国家确定契约。阿根廷使用当前批量 Payouts 契约；巴西使用 当前单笔 Transaction Intent 契约。对于其他国家，查询当前国家指南；如果 未返回经过验证的契约，则停止并提示 BLOCKED: verified Payouts country contract required。
3. 创建 Payout 必须仅在服务端进行，并且需要特权权限。要求通过身份验证并获得 明确的操作员授权，从持久化的可信指令存储库加载金额和目标，并写入持久化 审计记录。调用方只能提供不透明的指令 ID。
4. 必须明确启用测试模式，并发送官方 Payouts 测试标头。生产环境必须对准确序列化 后的请求体使用 Ed25519 签名。绝不硬编码测试模式、私钥、目标账户或 Access Token。
5. 成功的 HTTP 响应表示异步受理，并非最终入账。持久化 ID/状态，并通过查询和 Webhooks 进行对账。
6. 如果经过验证的国家契约使用 REST，且检测到的官方 SDK 未提供该资源，则不要 仅为 Payouts 安装 SDK。如果使用官方 SDK，LOCK 1 仍要求授权并使用最新稳定版本。

报告成功前，运行：

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-payouts-integration.mjs" . "{AR|BR}"

---

步骤 1 — 解析 $ARGUMENTS 并询问缺失的上下文

$ARGUMENTS 可包含以下标志的任意组合。缺少的任何信息都必须通过 AskUserQuestion 分批询问，每批不超过 4 项。

标志	值
country=	AR / BR / MX / CL / CO / PE / UY
product=	checkout-pro / checkout-api / bricks / qr / point / subscriptions / marketplace / wallet-connect / money-out / smartapps
mode=	取决于产品 — 见下方的产品矩阵
sdk=	node / python / java / php / ruby / dotnet / go（或使用原始 REST 时填 none）
client=	vanilla-js / react / ios / android / flutter / react-native（仅适用于包含客户端组件的产品）
lang=	es / en / pt（文档语言）
recurrent=	yes / no（Checkout API、Bricks）
3ds=	yes / no（Checkout API、Bricks）
marketplace=	yes / no（分账支付）
brick=	payment / card-payment / wallet / status-screen（仅当 product=bricks 时适用）
qr-mode=	static / dynamic / hybrid（仅当 product=qr 时适用）
subscription-model=	with-plan / without-plan-authorized / without-plan-pending（仅当 product=subscriptions 时适用）
marketplace-checkout=	checkout-pro / checkout-api / bricks-wallet（仅当 product=marketplace 时适用）
smartapps-agreement=	confirmed（仅当 product=smartapps 时适用；不得将未提供此项推断为已确认）
smartapp-kind=	main / mini（仅当 product=smartapps 时适用）
smartapp-ownership=	own / third-party（仅当 product=smartapps 时适用）

解析或推断出 product 后，立即应用 LOCK 5 规范化。产品矩阵、指南选择、CTA 解析和脚手架分支只能使用规范化后的内部值。仅用于展示的 slug checkout-api-orders 可以出现在最终建议元数据中，但绝不能用作内部 分支值。

步骤 1.a — 提问前自动解析（强制 — 必须先完成此步骤）

必须在调用任何 AskUserQuestion 之前运行此步骤。 在此处确定的每个维度都会从向导中移除。只有确实无法推断的维度才应询问开发者。跳过自动检测，转而询问开发者，是最常见的错误——切勿这样做。

对于每个维度，按以下顺序尝试这些解析来源：

维度	0：Agent 推断（步骤 1.a）	1：已保存的信息	2：仓库信号	3：询问
product	如果 Agent 根据消息关键词推断出结果 → 使用该结果，跳过问题	从 .mp-integrate-progress.md 读取	—	AskUserQuestion 选择器
country	如果 Agent 根据消息关键词推断出结果 → 使用该结果，跳过问题	从 .mp-integrate-progress.md 读取	无——不要搜索 country（不可靠，且会消耗令牌）	AskUserQuestion 选择器。保存答案。
sdk	—	—	必须运行 Glob 搜索：package.json→node、pyproject.toml/requirements.txt→python、pom.xml/build.gradle*→java、composer.json→php、Gemfile→ruby、*.csproj/Program.cs→dotnet、go.mod→go。匹配一项 → 已解析。匹配多项 → 选择活跃应用区域中的清单文件。没有匹配项 → 默认使用 node。	绝不要询问使用哪个 SDK；仅在安装/更新前询问是否授权。
client	—	—	检查 package.json 依赖：react/next→react、react-native/expo→react-native、*.xcodeproj→ios、Android build.gradle→android、pubspec.yaml→flutter。匹配一项 → 已解析。	AskUserQuestion（仅当产品包含客户端组件且无法明确判断时）
lang	—	—	根据 country 推导（BR→pt，其他→es）。	几乎不会询问——根据 country 默认
mode	—	从进度文件读取	使用 Grep 搜索 /v1/orders/order.create→orders；/v1/payments/payment.create→payments；/checkout/preferences/preference.create→preferences。产品矩阵可能将其限制为单一值（例如，checkout-pro → 始终为 preferences）。	AskUserQuestion（仅当矩阵允许多个值且 grep 未能明确判断时）

向导的具体操作顺序（先推断，后询问）：

0. 检查仓库中是否存在旧版 Instore API（在提问前）。 运行 Grep 搜索旧版 QR/Point 模式：

   • /mpmobile/instore/qr（QR Instore）
   • /instore/qr/seller/collectors（QR Instore V2）
   • /instore/orders/qr/seller/collectors（QR Dinámico）
   • /point/integration-api/devices/.*/payment-intents（Point PDV + Self Service）

   如果找到任何匹配项，且项目尚未完全迁移到 /v1/orders，请通过 AskUserQuestion 只询问一次：

   • 标题："Existing integration"
   • 问题：“我在你的项目 {file}:{line} 处发现了现有的旧版 Instore 集成。开始搭建前，你想先将它迁移到 Orders API 吗？”
   • 选项："Yes, migrate first (/mp-integrate migrate)" / "No, scaffold the new integration"
   • 如果选择“Yes” → 停止并提示：“运行 /mp-integrate migrate 迁移现有集成，然后返回以搭建新的集成。”
   • 如果选择“No” → 正常继续。本次会话中不要再次建议迁移。
   • 如果 $ARGUMENTS 已包含 migrate，则完全跳过此检查。

1. 检查 Agent 推断结果 — 如果 Agent 的 Step 1.a 已从开发者的消息中解析出 product= 和／或 country=，则这些维度已经确定。不要再询问。

2. 如果 .mp-integrate-progress.md 存在，请读取它 — 获取此前已确定的值。

3. 不要通过 grep 搜索国家/地区。 除非步骤 1–2 已经确定国家/地区，否则应通过 AskUserQuestion 询问。不要 grep 区域设置字符串、mercadopago.com.<tld> 或 currency_id — 这些操作会耗费令牌，还会产生错误匹配。

4. 对清单模式运行 Glob。如果匹配到一个 SDK 清单，则 SDK 已确定 — 不要询问。 使用为检测到的语言提供的官方 Mercado Pago SDK。绝不要推荐第三方 SDK。

5. 如果产品需要客户端，请对清单依赖项运行 Glob/Grep。如果只匹配到一个客户端，则客户端已确定。跳过客户端问题。

6. 根据国家/地区设置默认 lang。跳过语言问题。

7. 现在——并且只有现在——才按 Step 1.b 定义的顺序，每次调用一个工具，通过 AskUserQuestion 询问所有仍未确定的信息。每次得到答复后，都要将其写入 .mp-integrate-progress.md。

已知的 MCP 限制 — 国家/地区解析： Mercado Pago MCP 目前没有提供可返回开发者 site_id 的工具（application_list、quality_checklist 和 notifications_history 的响应中都不包含国家/地区信息）。OAuth 访问令牌可以用于直接调用 GET https://api.mercadopago.com/users/me，但令牌由 MCP 服务持有，不会暴露给插件客户端。在 MP 发布新 MCP 工具（例如 current_user_info 或通用的 proxy_request）之前，国家/地区解析只能这样进行：如果 .mp-integrate-progress.md 中记录了国家/地区，就读取它；否则通过 AskUserQuestion 询问并保存。不要浪费令牌在仓库中 grep 国家/地区线索（区域设置、URL、currency_id、site_id、应用名称启发式判断）——这些方法没有效果，而且问开发者一次更省时、更可靠。

Step 1.a.iii — 确认所有自动解析的内容（必须）

自动解析后，输出一个确认区块，列出推断出的每个值（不仅是国家/地区，也包括 SDK、客户端，以及仓库中推断出的任何其他维度）。然后，在询问任何向导问题之前，通过一次 AskUserQuestion 询问开发者：

• header="Confirm setup"
• 问题："I auto-detected the following from your repo. Is everything correct?"
• 选项：
  • "Yes, continue" — 使用自动解析的值继续 Step 1.b。
  • "No, let me correct" — 将用户可选择的自动解析值重新加入向导队列。不要将 SDK/语言加入该队列：重新运行仓库检测，并说明所选的官方 SDK，不要提供 SDK 选择器。

只有在没有任何内容可自动解析时，才跳过此确认（干净的仓库，没有清单、区域设置或现有的 MP URL）。这种情况下，向导直接进入提问环节。

示例区块：

I auto-detected the following from your repo:

  ✓ App:    My Store (123456789012345) — from application_list
  ✓ SDK:    node — from backend/package.json (mercadopago v2.12.0 already installed)
  ✓ Client: react — from frontend/package.json

Country will be asked next (not auto-detected).
Confirm the above to continue, or correct.

开发者必须明确选择接受自动解析的值。自动解析后绝不要静默跳转到 Step 1.b — 错误假设会因此一路传递到最终结果。

如果 Agent 已传入标志（country=、sdk=、mode= 等），也将其视为已确定。

1.a 后仍未确定的内容，都应在 1.b 中加入向导。

始终使用下方列出的官方 Mercado Pago SDK，无论开发者是否提到包装器或替代库。官方 SDK 由 Mercado Pago 维护，并与当前 API 保持一致。

Step 1.b — 使用 AskUserQuestion 选择器，一次询问一个问题

这是向导中最常被违反的规则。导致 v4 向导出现问题的两张截图，都是因为违反了本节规则。 请仔细阅读两遍。

在输出任何聊天内容之前先执行 STOP-TEST：

如果你的回复包含以下任何模式，说明操作有误 — 中止并改用 AskUserQuestion：

• Question N of M
• 1. Country / 2. Product / 3. SDK（编号问题列表）
• 包含选项代码的项目符号列表，例如 - checkout-pro — …
• 短语 Type the code、Reply with 或 Answer with
• 任何看起来像菜单的 Markdown，要求开发者用自由文本阅读并作答

这些都是 v3 反模式。开发者无法点击纯文本。他们的体验比你刚刚重写的 v3 插件还差。

硬性规则——绝无例外：

1. Step 0/1.a 之后的第一个工具调用必须是 AskUserQuestion。如果你的第一个工具调用是其他任何内容（Read、Write、Bash、search_documentation 等），那你就跳过了向导，直接在“聊天中提问”。停止并重新开始，使用 AskUserQuestion。
2. AskUserQuestion 每个维度单独调用一次工具，等待答案后再发起下一次调用。开发者会看到一个可通过方向键选择的交互式选择器。
3. 第一次调用 AskUserQuestion 之前的聊天输出必须不超过 3 行短句——每个自动解析的维度占一行，另可加一行“现在我会询问其余信息”。不要使用菜单、编号列表，也不要说“我会问你 4 个简短问题”。
4. 在 AskUserQuestion 调用之间：最多输出一行确认，然后立即进行下一次调用。不要总结进度，也不要显示“Question N of M”。
5. 如果某个维度确实无法用 4 个选择器选项涵盖，选择器会自动添加一个允许开发者自由输入的“Other”选项——使用该选项，不要把问题拆成两个。

AskUserQuestion 调用顺序——仅适用于 Step 1.a 后仍未确定的维度。跳过已知的维度。对于所选产品在 Product Matrix 中标记为 n/a 的维度，不要提问。

顺序	维度	标题	显示的选项
1	product	"Product"	将最有可能的 4 个产品显示为按钮，并自动提供“Other”作为后备选项。按以下优先级选择 4 个：checkout-pro、bricks、checkout-api、subscriptions（最常见）。其余选项（qr、point、marketplace、wallet-connect、money-out、smartapps）可通过“Other”选择。
2	mode	"Mode"	先对照 LOCK 2。 当 LOCK 2 显示“Skip the mode question”时，完全跳过。提问时，只显示 LOCK 2 明确允许所选产品使用的模式。绝不要将“Orders API”作为 checkout-pro 的选项。
3	client	"Client"	仅当产品包含客户端组件且仓库信号模糊不清时提问。显示最有可能的 3 个选项，以及 Other。
4	brick	"Brick"	仅当 product=bricks 时提问。选项：payment / card-payment / wallet / status-screen。
5	qr-mode	"QR mode"	仅当 product=qr 时提问。选项：static / dynamic / hybrid。
5.5	subscription-model	"Subscription"	仅当 product=subscriptions 时提问。选项：with-plan / without-plan-authorized / without-plan-pending。
5.6	marketplace-checkout	"Marketplace"	仅当 product=marketplace 时提问。选项：checkout-pro / checkout-api / bricks-wallet。
5.7	smartapps-agreement	"Agreement"	仅当 product=smartapps 时提问。询问是否已确认与 Mercado Pago 签订的有效商业/集成协议。选项：confirmed / not confirmed。如果未确认，在进行任何写入前停止。
5.8	smartapp-kind	"SmartApp type"	仅当 product=smartapps 且协议已确认时提问。选项：main / mini。
5.9	smartapp-ownership	"Terminal use"	仅当 product=smartapps 且协议已确认时提问。选项：own / third-party。
6	recurrent	"Recurrent"	仅当所选产品在矩阵中标记为 yes 时提问。选项：yes / no。
7	3ds	"3DS"	仅当矩阵中标记为 yes 时提问。选项：yes / no。
8	marketplace	"Splits"	仅当矩阵中标记为 optional 时提问。选项：yes / no。
此表中有意不包含 sdk —— 请参阅上文的 LOCK 1。绝不会通过 AskUserQuestion 询问 SDK。

绝不询问 environment。 Mercado Pago 不再提供沙盒／生产环境切换。生产凭证和测试用户凭证都使用 APP_USR- 前缀；区别在于凭证属于真实账户还是测试用户（由 mp-test-setup 处理）。不要提供“Environment: production / test”选择器。不要编写根据 NODE_ENV 切换 MP 基础 URL 的代码。

步骤 1.b.ii —— 不进行过早的 MCP 调用来确定 mode

先使用下方的产品矩阵。如果所选产品对应的 mode 单元格已确定，则使用该值，不要连接 MCP。

只有当产品／mode 组合不存在，或捆绑源中的信息确实含糊不清时，才使用 mcp__plugin_mercadopago_mcp__search_documentation，并使用类似 "{product} orders api {country}" 的查询。这是由 MCP 支持的备用方案：紧接着该查询之前进行身份验证，而不是提前验证。绝不要对 checkout-pro 执行此操作 —— LOCK 2 已禁止该产品使用 Orders。

如果备用文档明确确认了某种 mode，则在本次运行中使用该值。如果没有明确确认，则不要提供未经验证的 mode。

制定此规则是因为 v4 向导曾为 Checkout Pro 提供 Orders，但该产品并不存在相应 API。绝不要提供当前 MP API 中不存在的 mode，即使有人传闻该 mode 即将推出或即将可用。

country 通常会出现在此列表中。 目前 MCP 不会返回 site_id，因此除非仓库信号或持久化状态已在 1.a 中确定该值，否则你需要询问。使用 header="Country"，并将 AR、BR、MX、CO 设为按钮（最常见的 4 个选项）——选择器会自动添加“Other”选项，供开发者输入 CL、PE 或 UY。得到回答后，将其保存到 .mp-integrate-progress.md。

步骤 1.b.i —— 对话应呈现的样子（具体示例）

错误（v3 反模式，与截图所示完全一致）：

Now I need a few details to scaffold the right integration:

1. Country — Which site/country are you integrating for?
- MCO — Colombia
- MLA — Argentina
…

2. Product — Which Mercado Pago product…
…

3. SDK / Language — What stack are you using?
…

正确：

✓ App: My Store (123456789012345) — from application_list
✓ SDK: node — from package.json
(Country will be asked next — not auto-detected.)

→ 然后立即调用 AskUserQuestion 询问 product。开发者选择后，用不超过 1 行确认。接着调用下一个 AskUserQuestion。依此类推。

步骤 1.c —— 立即保存所有已收集的数据

持久化的黄金规则：每一项收集到的信息——通过推断、向导、MCP 或任何其他方式获取——都要在收集后立即写入 .mp-integrate-progress.md。除非开发者明确更改，否则绝不再次询问。

每次运行开始时，先读取此文件并使用其中找到的所有值。只询问确实缺失的维度。

要持久化的字段（每项确定后立即写入，不要等到最后）：

# mp-integrate progress

- country: AR
- product: checkout-pro
- mode: preferences
- sdk: node
- client: react
- lang: es
- credential_type: test
- application_id: 123456789012345
- brick: card-payment
- qr_mode: dynamic
- subscription_model: with-plan
- marketplace_checkout: checkout-pro
- recurrent: no
- three_ds: no

规则：

• 每确定一个字段后就写入文件，而不是只在向导结束时写入。
• 如果开发者在会话中更改某个值（例如“其实我想选 Brazil”），立即更新文件。
• 如果 .gitignore 中尚未包含 .mp-integrate-progress.md，则将其添加进去。
• 成功渲染 bundle 后删除该文件；取消或出错时保留，以便下次运行时继续使用。

产品矩阵 — 哪些标志适用（哪些不适用）

产品	sdk	client	mode（允许的值）	recurring	3ds	marketplace	子标志
checkout-pro	是	可选	仅限 preferences — Checkout Pro 没有 Orders API 模式	不适用	不适用	可选	不适用
checkout-api	是	是	orders（所有国家/地区）	是	是	可选	不适用
bricks	是（服务端）	是	内部 payments 路由；后端因变体而异，详见 LOCK 9	是（payment、card-payment）	是（payment、card-payment、status-screen）	可选	brick=
qr	是	不适用	orders（所有国家/地区）	不适用	不适用	不适用	qr-mode=
point	是	不适用	orders（所有国家/地区）	不适用	不适用	不适用	不适用
subscriptions	是	有条件（授权合同使用 MercadoPago.js）	不适用（自有 preapproval API）	隐式	不适用	可选	subscription-model=
marketplace	是	有条件	Checkout Pro/Wallet 使用 preferences；Checkout API 使用 payments	不适用	不适用	隐式	marketplace-checkout=
wallet-connect	是	不适用	orders	不适用	不适用	不适用	不适用
money-out	有条件（已验证的 REST 有效）	不适用	不适用（Payouts；合同因国家/地区而异）	不适用	不适用	不适用	国家/地区决定合同
smartapps	不适用（私有套件 AAR）	Android	不适用	不适用	不适用	不适用	smartapp-kind=、smartapp-ownership=

如果某产品的 mode 单元格是固定值（单一值或 n/a），切勿询问开发者有关 mode 的问题 — 直接使用该值或跳过该问题。

---

第 2 步 — 确定国家/地区域名和货币

国家/地区	Site ID	域名	货币	默认语言
阿根廷	MLA	www.mercadopago.com.ar	ARS	es
巴西	MLB	www.mercadopago.com.br	BRL	pt
墨西哥	MLM	www.mercadopago.com.mx	MXN	es
智利	MLC	www.mercadopago.cl	CLP	es
哥伦比亚	MCO	www.mercadopago.com.co	COP	es
秘鲁	MPE	www.mercadopago.com.pe	PEN	es
乌拉圭	MLU	www.mercadopago.com.uy	UYU	es

如果未提供 lang=，则使用该国家/地区的默认语言。

---

步骤 3 — 查找文档和上下文

按层级查找文档。各国家/地区的官方 llms.txt 始终是最新的——开发者可以访问互联网，且文件只有几 KB，因此应先获取该文件。如果无法访问，则妥善回退。

层级	来源	身份验证	适用情况
1	https://www.{country_domain}/developers/llms.txt（WebFetch — 官方、始终为最新）	无	始终优先——使用已解析的国家/地区域名获取。如果失败（403、超时），则转到层级 2。
2	{plugin_base}/skills/mp-integrate/references/products.md（捆绑文件）	无	始终使用——产品指南、API 参考、代码片段、各国家/地区专属测试卡。
3	mcp__plugin_mercadopago_mcp__search_documentation	MCP OAuth	仅作为后备，但 SmartApps 除外，该产品必须使用此层级——仅当层级 1–2 未涵盖该组合时使用；对于 product=smartapps，始终使用。

层级 1 的国家/地区域名：

国家/地区	llms.txt URL
AR (MLA)	https://www.mercadopago.com.ar/developers/llms.txt
BR (MLB)	https://www.mercadopago.com.br/developers/llms.txt
MX (MLM)	https://www.mercadopago.com.mx/developers/llms.txt
CO (MCO)	https://www.mercadopago.com.co/developers/llms.txt
CL (MLC)	https://www.mercadopago.cl/developers/llms.txt ← 不带 .com
PE (MPE)	https://www.mercadopago.com.pe/developers/llms.txt
UY (MLU)	https://www.mercadopago.com.uy/developers/llms.txt

必须先于步骤 3 解析国家/地区。 未解析国家/地区时，绝不获取层级 1 的内容。

如果层级 1 获取失败： 静默回退到层级 2（references/products.md）。不要显示错误或重试。

仅在确实需要层级 3 时： 直接尝试调用 search_documentation。如果该工具不可用或返回身份验证错误，则调用 mcp__plugin_mercadopago_mcp__authenticate，使用开发者的语言显示 OAuth 链接，并告知其使用 Cmd+Click（Mac）或 Ctrl+Click（Windows/Linux），不要将 URL 复制到外部浏览器。开发者返回后，直接重试 search_documentation。不要调用 application_list 进行探测。

层级 3 — MCP 查询模板（后备）

构建 1–3 个有针对性的查询，并分别调用 mcp__plugin_mercadopago_mcp__search_documentation。使用已解析文档语言对应的 language。

查询模板（针对所选产品/模式/SDK，使用最具体的 1–3 个）：

需求	查询模板
服务端创建	"{product} create {mode} {sdk} {country}"（例如："checkout-pro create preference node argentina" 或 "checkout-api create order node argentina"）
客户端/UI	"{product} {client} initialization {brick?}"（例如："bricks react payment brick initialization"）
令牌化（Checkout API / Card Payment Brick）	"card token {client} {country}"
3DS 挑战	"3ds {product} {sdk}"
Webhook 处理	跳过——交由 mp-webhooks 技能处理
测试卡/用户	跳过——交由 mp-test-setup 技能处理
Marketplace 分账	"marketplace split {sdk} application_fee"
订阅计划/预审批	"subscriptions preapproval {sdk}"
付款转出（旧别名：Money Out）	"payouts money transfer {country} {sdk}"
Wallet Connect	"wallet connect agreements payer token orders {sdk} {country}"
SmartApps	`"smartapps {main

最多发起 3 个查询。如果查询返回的结果过于宽泛，则细化一次后停止。

当 MCP 返回文档但没有代码片段时（诚实的回退方案）

如果 search_documentation 返回的结果只有概览或着陆页文案（没有代码块），请勿编造代码。请准确输出：

没有可验证的代码片段，适用于 {product} / {country} / {sdk}。 MCP 返回了此组合的文档，但没有代码片段。请手动查看指南：https://{DOMAIN}/developers/{LANG}/docs/{product-slug}/overview

然后停止。具体来说：

• 请勿根据训练数据记忆还原代码——还原出的代码片段（这就是产生 CardForm 幻觉的原因）绝不能冒充经过 MCP 验证的内容。
• 请勿随意再次调用 WebFetch 来替代。 单次官方国家/地区 llms.txt 请求属于 tier 1，捆绑参考资料属于 tier 2，MCP 属于 tier 3。如果这些来源都不包含经过验证的代码片段，请说明该片段不可用。
• 明确标记输出为“没有可验证的代码片段”，让开发者知道这是不可用内容，而非已验证内容。

---

步骤 4 — 组装捆绑内容

SmartApps 捆绑内容覆盖规则

当 product=smartapps 时，不要呈现下方通用的服务端/网页结账捆绑内容，也不要创建 .env 凭据。请根据 references/guides/smartapps.md 和经过身份验证的 MCP 结果，呈现 SmartApps 专用捆绑内容，并包含以下部分：商业协议、Android 项目资格、应用类型（main|mini）、所有权（own|third-party）、最新私有 SDK 构件、Manifest/初始化约定、仅使用 SDK 的支付流程、静态验证、开发终端测试和认证测试。将任何仍依赖私有工具包或终端的内容标记为受阻；绝不要用臆测的公共 SDK 或 API 调用来替代。然后继续执行步骤 4.5。

Payouts 捆绑内容覆盖规则

当 product=money-out 时，将捆绑内容标记为 Payouts，并根据 references/guides/payouts.md 和当前国家/地区来源呈现仅限服务端的捆绑内容。不要呈现通用的客户端/支付表单部分，不要请求公钥，也不要创建结账 CTA。请包含以下部分：国家/地区约定、特权服务边界、持久化的可信指令存储库、操作员授权、审计跟踪、幂等性、明确的测试模式、生产环境 Ed25519 签名、资源查询、通知、安全的自动化测试和生产发布控制。若经过验证的官方 SDK 未提供 Payouts 功能，请使用原始 REST；不要仅为封装 fetch 而安装支付 SDK。

请严格按照以下结构呈现结果。代码块应来自已确定的文档层级（尽可能逐字呈现）。不要编造请求负载或端点。

# Mercado Pago Integration — {Product} ({Country} · {SDK} · {mode})

## 1. Install
```bash
{install command for the chosen SDK}
```

## 2. Credentials

Get your credentials from the Mercado Pago Developer Dashboard:
👉 **https://{DOMAIN}/developers/panel/app**

- Under your application, click **Credentials**.
- For **testing**: click the **{test_tab}** to get test credentials.
- For **production**: use the credentials in the **{prod_tab}** tab.

Credentials come in two valid prefixes: **`APP_USR-`** (Orders API, Checkout Pro, Point, QR; also test-user credentials from `create_test_user`) and **`TEST-`** (Checkout API, Bricks, Payments API). Both are valid and actively issued — never tell a developer to change their prefix. What matters is which tab they come from: {test_tab} = test, {prod_tab} = production.

Create `.env` from the template below (**never commit `.env`**):

```
MP_ACCESS_TOKEN=APP_USR-...   # server-side, keep secret
MP_PUBLIC_KEY=APP_USR-...     # client-side, can be public
MP_WEBHOOK_SECRET=...         # from Dashboard → Webhooks → Signature secret
APP_URL=http://localhost:3000
```
Also ensure `.env` is in `.gitignore` (and `.env.example` is **not** ignored).

## 3. Server code
```{language}
{snippet from the resolved documentation tier — server-side creation, e.g., create order/preference/subscription/disbursement}
```

## 4. Client code (if applicable)

**Always show the total amount above the payment form** (do not bury it inside the brick):

```html

<p class="checkout-total">Total: <strong>{currency} {amount}</strong></p>
```

```{language}
{snippet from the resolved documentation tier — tokenization, brick mount, redirect, etc.}
```

**Payment feedback states — include ALL THREE in the scaffold (not as TODOs):**

```jsx
// Loading state — show while the payment is processing
{isLoading && (
  <div className="checkout-loading">
    <p>Processing your payment…</p>
  </div>
)}

// Success state
{paymentStatus === 'approved' && (
  <div className="checkout-success">
    <h2>Payment approved!</h2>
    <p>Order: <strong>{orderId}</strong></p>
    <p>Next step: run <code>/mp-review</code> to validate your integration before going live.</p>
  </div>
)}

// Error state — actionable, not the raw API error
{paymentStatus === 'error' && (
  <div className="checkout-error">
    <p>Payment could not be processed: {errorMessage}</p>
    <p>If testing, check your test card data or try a different scenario code —
       e.g. cardholder name <strong>APRO</strong> for approved, <strong>FUND</strong> for insufficient funds.</p>
  </div>
)}
```

> These three blocks are **part of the default scaffold on every run** — never leave them as `{/* TODO */}` placeholders. Adapt the conditional syntax to the detected client framework (React shown; use the equivalent for vanilla-js, Vue, etc.).

## 5. Webhook receiver
> Webhook validation is handled by the `mp-webhooks` skill — invoke it next, or run `/mp-integrate webhook` to scaffold the receiver with HMAC validation.

## 6. Test
- Get test credentials and test users via the `mp-test-setup` skill (or run `/mp-integrate test-setup`).
- Test cards for the country: see `references/products.md` (AR/BR/MX/CO/CL) or query MCP for others.
- After your first successful test payment → run `/mp-review` (**step 6 of 7 — MANDATORY before production**).

## 7. Docs (country-specific)
- Product guide: https://{DOMAIN}/developers/{LANG}/docs/{product-slug}/overview (fallback: /landing)
- API reference: https://{DOMAIN}/developers/{LANG}/reference

## 8. Gotchas
{render the gotchas for the chosen product from the Gotchas Bank below}

SDK	安装命令
node	npm install mercadopago
python	pip install mercadopago
java	Maven: com.mercadopago:sdk-java / Gradle equivalent
php	composer require mercadopago/dx-php
ruby	gem install mercadopago-sdk
dotnet	dotnet add package MercadoPago
go	go get github.com/mercadopago/sdk-go
react (client)	npm install @mercadopago/sdk-react
vanilla-js (client)	<script src="https://sdk.mercadopago.com/js/v2"></script>
ios	SPM: https://github.com/mercadopago/sdk-ios
android	Gradle: com.mercadopago:sdk

---

步骤 4.5 — 提议搭建文件

⚠️ 强制要求——必须先向用户显示捆绑内容，再执行此步骤。

步骤 4 中的完整捆绑内容必须先以渲染后的 Markdown 输出形式出现在聊天中，然后才能调用 AskUserQuestion——每次运行都必须如此，即使同一会话的上一轮已经加载过参考资料，也不得跳过呈现。绝不要说“参考资料已加载”或类似的话，然后直接跳到这里。如果捆绑内容尚未在当前回复中明确呈现，请立即先呈现。

呈现捆绑内容后，在列出后续步骤之前，立即调用 AskUserQuestion，并附上：

• header="Scaffold files"
• 问题："Do you want me to write these files to your project now?"
• 选项：
  • "Yes, write the files" → 执行下面的脚手架步骤
  • "No, just the code" → 跳到第 5 步

如果开发者选择生成脚手架，按顺序执行以下步骤（每一步都依赖前一步）：

1. 仅在获得授权后安装或更新 SDK — 查询官方注册表并应用 LOCK 1。如需更改，先征求明确授权，并提供确切的稳定版本，然后再在包含服务端清单文件的目录中运行 npm install mercadopago@latest（或针对已检测到的 SDK 执行等效的稳定版命令）。切勿选择预发布版本。更新锁文件，调整不兼容的集成代码，运行相关测试，并在退出代码非零时停止。如果当前依赖解析出的版本已是注册表中的稳定版本，则不要对其进行修改；报告已核实的版本。

2. 写入服务端代码片段 — 创建或编辑服务端文件（例如 backend/index.js、backend/src/routes/mercadopago.js），插入第 4 步的代码片段。如果文件已存在，则将新路由添加到现有路由之后，而不是覆盖文件。

   当 product=point 时： 写入服务端集成后立即运行 Point 服务端验收检查。继续操作或报告成功前，必须修复所有失败项：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-point-server.mjs" "{server_file}"
   

   当 product=qr 时： 写入服务端集成后立即运行 QR 服务端验收检查。在应用实际收款 CTA 中接入客户端后，还要运行客户端验收检查。继续操作或报告成功前，必须修复所有失败项：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-qr-server.mjs" "{server_file}"
   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-qr-client.mjs" "{client_file}" 'data-mp-qr-cta="create-order"' "/api/qr/orders"
   

   当 product=bricks 时： 专用 Brick 页面、服务端路由（如适用）、运行时公共配置和 CTA 接线全部写入后，应用 LOCK 9 并运行全应用验证器：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bricks-integration.mjs" . "{brick}"
   

   当 product=subscriptions 时： 订阅 CTA、注册页面、令牌化（获得授权时）、服务端路由和生命周期路由全部写入后，应用 LOCK 10：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-subscriptions-integration.mjs" . "{subscription-model}"
   

   当 product=marketplace 时： 卖家 OAuth、加密持久化/刷新、选定的结账契约以及卖家连接和买家结账 CTA 均已写入后，应用 LOCK 11：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace-integration.mjs" . "{marketplace-checkout}"
   

   当 product=wallet-connect 时： 专用页面、结账 CTA 接线、账户关联路由、加密的付款方令牌存储以及 Orders API 路由全部写入后，应用 LOCK 12：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-wallet-connect-integration.mjs" .
   

   当 product=smartapps 时： Android Manifest、应用程序初始化和 SDK 付款流程全部写入后，应用 LOCK 13。使用已解析的应用类型和所有权运行验证器。除非已提供真实的最新套件工件并成功编译，否则不得报告 AAR 为最新版本或构建通过：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-smartapps-integration.mjs" . "{main|mini}" "{own|third-party}"
   

   当 product=money-out 时： 特权服务、持久化指令存储库、授权/审计控制、已解析的国家/地区契约、明确的测试模式、生产签名和查询路由全部写入后，应用 LOCK 14：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-payouts-integration.mjs" . "{AR|BR}"
   

2.5. checkout-pro 和 checkout-api — 必须发现结账 CTA（其他所有产品均跳过）：

对这两种结账产品，此步骤均为必需。只有确定了具体的 CTA 目标，脚手架才算完整。这两种产品使用相同的检测器，但在第 3.5 步中的接线方式不同：

• checkout-pro：在已确定的 CTA 位置放置一个可见的 使用 Mercado Pago 付款 按钮；该按钮向偏好设置创建路由提交请求，并重定向到 init_point。
• checkout-api：将已确定的 CTA 链接到新的独立结账页面。

重用 LOCK 5 的结果。如果因任何原因无法使用该结果，则从项目根目录恰好运行一次内置解析器：

node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-checkout-cta.mjs" "{product}" .

首先，将 {product} 替换为 LOCK 5 返回的规范化内部值。解析器会扫描 HTML 和常见的 Web 模板／组件（JSX、TSX、Vue、Svelte、Astro、PHP、ERB、EJS、Handlebars、Twig、JavaScript 和 TypeScript）。它会根据可见文本、属性以及实际的点击／导航处理程序中的语义证据进行评分；其中不包含任何特定于应用的选择器。

解析目标：

1. 只有当元素、可见文本、位置和当前处理程序共同表明这是启动结账的最终操作时，匹配结果才符合要求。通用导航链接或产品卡片上的“购买”按钮不足以作为证据。
2. 排除生成的支付表单中的提交按钮（form-checkout、type="submit"、mp-pay-btn）——该按钮用于提交付款，不是进入表单的链接。
3. 更改候选项之前，先读取其现有的 onclick、onClick、href 或 addEventListener。
4. 如果检测器返回 status=selected，则使用该 CTA 并报告 {file}:{line}。此结果为强制要求；不得将其降级为“未找到”。
5. 如果返回 status=ambiguous，请通过 AskUserQuestion 询问哪个候选项是结账 CTA（最多四个候选项）。继续搭建之前必须先选定目标。
6. 如果返回 status=not_found，请检查应用实际的购物车／订单／商品入口页面，并通过 AskUserQuestion 询问应将新的结账 CTA 插入何处（最多四个具体的文件／位置选项）。开发者选择后，设置 cta_status=create 并使用该确切位置。
7. 如果开发者在结果为 ambiguous 或 not-found 后未提供目标，则停止并报告 BLOCKED: checkout CTA target required。绝不可完成搭建、悄悄省略 CTA 或报告成功。

为第 3.5 步保存 {cta_file}、{cta_line_or_region}、{cta_selector}、{cta_status} 以及任何现有处理程序。暂时不要编辑；必须先创建服务器路由，以及 Checkout API 所需的新结账页面。

3. 仅限 checkout-api — 始终在新文件中创建独立的结账页面 — 使用项目的架构，根据第 4 步生成客户端表单。对于 checkout-pro，直接跳到第 3.5 步；Checkout Pro 会重定向到 Mercado Pago，不得创建本地支付表单页面。

   对于 Checkout API，此要求无条件适用：只有在第 2.5 步确定了入口 CTA 的位置后，才能创建页面。

   • 服务器渲染／静态应用： 为结账页面创建新的 HTML／模板文件，并创建提供该文件的 GET 路由或静态 URL。
   • React／Vue／Angular／SPA： 创建新的页面／屏幕组件文件，并通过应用现有路由器注册专用路由。
   • 移动应用： 创建新的页面文件，并在现有导航栈中注册。
   • 没有路由器的单文件应用： 仍须创建单独的结账页面文件，并通过 URL 提供访问。不要在现有文件中追加另一个隐藏视图。

   分离规则： 绝不可将生成的支付表单放入现有的购物车、商品、抽屉、模态框、手风琴、选项卡或条件隐藏区域。绝不可将表单标记追加到现有页面文件中。可以导入或复用共享布局、样式和组件，但结账页面本身必须由其新文件负责，并通过其独立的路由／URL／导航目标打开。

   复用项目的命名和路由约定。记录：

   • {checkout_screen_file} — 为该页面新建的文件；
   • {checkout_screen_destination} — 其路由、URL 或导航名称；
   • {checkout_screen_invocation} — 打开该页面所需的框架适用代码。

   在新文件存在且路由／导航注册已验证之前，不要将任何内容链接到该目标。

   Checkout API 公钥传递 — 必须遵循且与应用无关：

   1. 在生成结账页面之前，先检测目标应用现有的客户端配置惯例。对于 React、Next.js、Vue、Nuxt、Angular、移动端或服务端渲染模板，沿用其既定的公共运行时配置；不要将 Express 专用模式强加给其他技术栈。
   2. 绝不要在生成的客户端文件中放入 %MP_PUBLIC_KEY% 或其他文本替换标记。也不要依赖重写结账 HTML 响应：浏览器、CDN、Service Worker 和静态托管服务可能会保留包含字面标记的过时文档。
   3. 对于带有后端的原生／无构建应用，使用项目的服务端框架和路由惯例添加 JSON 配置端点。该端点必须在服务端读取 MP_PUBLIC_KEY，返回 { publicKey }，发送 Cache-Control: no-store, max-age=0，并在变量缺失时返回非 2xx 响应及清晰的错误信息。结账页面必须先使用 cache: 'no-store' 请求该端点，再创建 MercadoPago。
   4. 对于基于构建的客户端，只能使用框架的公共变量惯例（例如现有的 Vite、Next.js、Nuxt 或 Angular 机制），并说明是否需要重启服务端或重新构建。不要暴露 MP_ACCESS_TOKEN 或任何其他私有凭据。
   5. 仅有静态服务器时，无法完成 Checkout API，因为创建付款需要后端。如果应用当前通过静态文件服务器运行，请将生成的后端接入项目实际的启动／开发命令，并告知开发者使用该命令。绝不要在让他们直接打开 HTML 文件的同时声称操作成功。
   6. 在生成的表单或页面根元素上标记 data-mp-public-key-source="runtime-endpoint" 或 data-mp-public-key-source="framework-public-config"，并与实际采用的策略一致。
   7. 在确认成功之前，验证生成的客户端不含未解析的公共密钥标记；选择端点策略时，客户端和服务端使用完全相同的配置路由；缺少密钥时的处理清晰可见且可执行；并且结账页面是通过应用实际的服务端／路由访问的。

   Checkout API 安全字段完整性——强制要求，适用于任何应用：

   • 构建最精简的有效表单。始终显示的卡片输入项为 cardNumber、expirationDate、securityCode 和 cardholderName。

   • 付款人邮箱和身份信息是必需的支付数据，但并非自动要求作为可见输入项。请复用已从经过身份验证的买家／会话／购物车中获取的可信值。仅当应用没有这些值时才渲染相应输入项，并在表单上通过 data-mp-payer-email-source="form|application" 和 data-mp-payer-identification-source="form|application" 标记所选策略。

   • SDK JS CardForm 映射要求包含 issuer、installments 和 identificationType，即使产品界面不显示这些控件也不例外。每项都必须且只能渲染一个 <select>，并将其放在表单内，使用 data-mp-sdk-required-field="issuer|installments|identificationType" 标记，同时在 mp.cardForm({ form: ... }) 中引用其准确 ID。省略这三项中的任何一项都属于脚手架构建失败，因为 SDK 会在支付方式生命周期中填充它们；若对应的 DOM 目标不存在，安全 iframe 字段可能无法响应。

   • 当这三个控件中的某个不属于可见界面时，请使用真正隐藏的生命周期节点：<select hidden aria-hidden="true" tabindex="-1">。不要使用 disabled，因为禁用的控件无法参与表单／SDK 状态管理。这些隐藏的 select 是 SDK 内部接线，不是后端信任的支付数据。

   • 根据已确定的国家／地区和买家上下文推导身份类型。例如，巴西的个人买家使用 CPF。若身份类型已知，请将必需的 identificationType 生命周期 select 保持隐藏；只有当应用确实支持多种类型且无法推断正确类型时，才将其显示为带标签的选择器。

   • 默认将必需的 issuer 生命周期 select 保持隐藏。仅当支付方式元数据报告的 additional_info_needed 中包含 issuer_id 时，才将其显示为带标签的选择器；不要在 Orders API payment_method 中发送 issuer_id。

   • 对于最简的一次性支付流程，请将必需的 installments 生命周期 select 保持隐藏，并在服务器端强制设置 installments: 1。只有当开发者明确希望提供分期付款选项时，才将其显示为带标签的选择器。切勿信任浏览器中的隐藏值，而应遵循服务器端规则。

   • mp.cardForm({ form: ... }) 中注册的每个字段，在运行 mp.cardForm(...) 前都必须在 DOM 中恰好有一个对应元素。若已选择从应用状态获取某个可选字段，或决定不在界面中显示该字段，就不要再配置它。

   • form.id 中的表单 ID 必须与渲染出的 <form id="..."> 完全一致。

   • 为每个字段渲染始终可见的标签，并将其本地化为项目所用语言。MM/AA 和 CVC 等占位符只是提示，不是标签，也可能不会显示在安全 iframe 内。

   • 对于 iframe 字段（cardNumber、expirationDate、securityCode），SDK 宿主 <div> 必须保持为空且可交互。切勿在宿主或其 iframe 上添加 disabled、readonly、pointer-events: none 或遮挡内容的装饰元素。

   • 为每个安全宿主设置非零高度和 position: relative；注入的 iframe 应设置 display: block、width: 100% 和 height: 100%。可见边框应属于宿主，而非覆盖层。

   • 仅当新的结账页面路由已显示且宿主尺寸非零时，才挂载安全字段。使用应用的生命周期／路由钩子或 requestAnimationFrame；切勿将其初始化到 display: none 的位置，也不要使用任意 setTimeout 来实现可见性。

   • 每个可见表单实例只能挂载一次。在 SPA 中重新挂载前，请卸载／销毁先前的 SDK 控制器或字段实例。

   • 将每个安全宿主与外部可见标签及可访问性关联方式组合使用，例如：

     <div class="checkout-field" role="group" aria-labelledby="expiration-label">
       <span id="expiration-label" class="checkout-label">银行卡有效期（MM/AA）</span>
       <div id="form-checkout__expirationDate" class="secure-input"></div>
     </div>
     

   • 仅在获取或提交期间禁用付款提交按钮。切勿将禁用银行卡数据字段作为加载状态管理的一部分。

   • 在 onFormMounted 中，验证每个安全主机是否恰好包含一个 iframe、尺寸是否非零、是否有可见的外部标签，以及主机和 iframe 解析出的 pointer-events 是否都不是 none。在控制台和可见的表单错误中显示失败信息；不得将脚手架报告为成功。

   继续之前，双向比对已注册的字段 ID 与渲染出的 ID。然后检查生成的源代码，查看是否有影响安全主机或其祖先元素的 disabled、readonly、aria-disabled、inert、覆盖层和 pointer-events。缺少标签、隐藏挂载、重复实例和不可交互的主机均属于脚手架失败，必须立即修复。

   为每个可见字段包装元素添加 data-mp-field="{fieldName}"；为 3 个 SDK iframe 主机添加 data-mp-secure-field="cardNumber|expirationDate|securityCode"；为 3 个必需的 CardForm 生命周期选择框添加 data-mp-sdk-required-field="issuer|installments|identificationType"。表单必须使用上述来源标记声明付款人电子邮件和身份信息来自表单还是应用状态。编写新页面后，运行确定性验收检查：

   # runtime-endpoint strategy: pass the file that implements the config route
   node "${CLAUDE_PLUGIN_ROOT}/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 "${CLAUDE_PLUGIN_ROOT}/scripts/validate-checkout-screen.mjs" "{checkout_screen_file}" "" "{cta_file}"
   

   如果检查失败，请修复新页面并重新运行。此命令以代码 0 退出之前，绝不显示脚手架成功摘要。

3.5. checkout-pro 和 checkout-api — 始终接通已确定的 CTA：

必须有一个已确定的 CTA。保留周围布局，并沿用项目的按钮类和无障碍规范。为最终元素添加 data-mp-checkout-cta="{product}"，以便确定性检查验证集成。

**当 product=checkout-api 时：**保留现有 CTA 的可见文本和样式，然后仅替换其导航行为，使其打开 {checkout_screen_destination}。

• 现有 <a>：添加 data-mp-checkout-cta="checkout-api"，并设置或更新 href="{checkout_screen_destination}"。
• Vanilla <button>：添加 data-mp-checkout-cta="checkout-api"，并将现有结账处理程序替换为唯一一项 window.location.assign('{checkout_screen_destination}') 操作。
• React/Vue/路由器应用：添加 data-mp-checkout-cta="checkout-api"，并使用现有的路由器导航 API。如果应用已使用客户端路由，不要引入 window.location。
• 当 cta_status=create 时，在步骤 2.5 中选定的确切位置插入一个符合项目样式的按钮或链接，并将其接通至新页面。

当 product=checkout-pro 时：在确定的位置放置一个可见按钮，标签为使用 Mercado Pago 付款（本地化为应用语言）。该按钮必须启动偏好项创建，并重定向至返回的 init_point；不得打开本地银行卡表单。

• 服务端渲染/静态应用：将选定的 CTA 替换为一个表单，或在选定区域插入表单，并将其提交至偏好项路由：

  <form action="{preference_route}" method="POST">
    <button type="submit" data-mp-checkout-cta="checkout-pro" class="{existing_button_classes}">
      使用 Mercado Pago 付款
    </button>
  </form>
  

• SPA／框架应用：保留一个可见的、符合项目样式的按钮，并带有 data-mp-checkout-cta="checkout-pro"；其唯一处理程序必须调用后端偏好设置路由，并跳转到返回的 init_point。移除旧的结账处理程序，不要再叠加第二个监听器。

• 绝不要为 Checkout Pro 创建第二个结账页面。选定的 CTA 位置就是 Mercado Pago 按钮应放置的位置。

编辑后必须进行验证：

1. 确认最终只有一个元素带有 data-mp-checkout-cta="{product}"。

2. 对于 Checkout API，确认 {checkout_screen_file} 是独立文件，{checkout_screen_destination} 指向该文件，并且 CTA 恰好有一个导航操作指向该目标。

3. 对于 Checkout Pro，确认可见按钮上显示 Mercado Pago，且会访问创建偏好设置的路由，该路由会重定向到 init_point。

4. 确认旧的 CTA 处理程序已移除，点击按钮不会触发两个结账流程。

5. 对于 Checkout API，确认没有把支付表单自身的提交按钮误认为入口 CTA，也没有将其重新接线为入口 CTA。

6. 运行确定性的 CTA 验收检查，并在继续之前修复任何失败：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-checkout-cta.mjs" "{product}" "{cta_file}" "{checkout_screen_destination_or_preference_route}"
   

   对于 Checkout Pro，还要运行服务端验证器。如果应用有 localhost 回退地址，该验证器会拒绝无条件设置 auto_return：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-checkout-pro-server.mjs" "{server_file}"
   

7. 报告 ✓ {cta_file}:{cta_line_or_region} → {checkout_screen_destination_or_preference_route}。对于 Checkout Pro 或 Checkout API，“CTA 未连接”都不算成功。

8. 创建 .env.example — 将模板变量（MP_ACCESS_TOKEN、MP_PUBLIC_KEY、MP_WEBHOOK_SECRET、APP_URL）写入 .env.example。只有在开发者明确选择导入凭据且 get_credentials 成功时，才使用真实值创建 .env；未经确认，不要覆盖现有的 .env。否则，绝不要创建 .env——开发者必须自行填写凭据。

9. 更新 .gitignore — 如果 .env、.env.*.local、.mp-integrate-progress.md 尚未添加，则将它们添加进去。 5.5. 脚手架成功后删除 .mp-integrate-progress.md — 此文件仅用于崩溃／取消后的恢复检查点。运行最终产品验证器之前、打印成功摘要之前，先将其移除。仅在运行取消、受阻或失败时保留。集成完成后绝不能留下此文件。

10. 完成所有写入后，打印针对具体产品的摘要。两种成功结果都必须包含已接通的 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

脚手架防护规则：

• 绝不要写入当前工作目录之外的文件。
• **如果通过 get_credentials 获取了凭据：**不要覆盖已确认的 .env；仅使用占位符创建 .env.example。
• **如果未导入凭据：**使用 APP_USR-... 占位符创建 .env.example。绝不要在此处创建 .env。
• 如果目标文件已存在且开发者说“全部写入”，则注入代码，而不是覆盖文件——以 +diff 样式预览显示变更内容。
• 如果任何写入失败，报告确切错误并停止；不要继续写入下一个文件。
• **禁止在 HTML 中注入凭据：**不要生成 %MP_PUBLIC_KEY%、.replace(...)、模板令牌替换或内联硬编码的公钥。使用检测到的框架的公共配置约定，或者为原生／服务端应用提供 no-store JSON 运行时配置端点。

---

第 5 步 — 建议后续步骤

最后始终列出：

1. 运行 /mp-integrate webhook，添加 webhook 接收器（包含 HMAC 验证）。

2. 运行 /mp-integrate test-setup，创建测试用户并充值。 2.5. **对于 Orders API 产品（checkout-api / qr / point — 所有国家）：**在列出后续步骤前，通过 AskUserQuestion 询问：

   • 问题："Orders API 需要测试买家用户才能处理付款。要我现在创建一个吗？"
   • 选项："Yes, create test user now" → 内联调用 mp-test-setup 技能；"No, I'll do it later" → 显示提醒："⚠️ 测试前运行 /mp-integrate test-setup — 没有测试用户时，Orders API 会返回 422。"
   • 注意：Card Payment 和 Payment Bricks 使用 Payments API，不需要走 Orders 买家流程。Wallet 仍需有买家登录 Mercado Pago；Status Screen 需要一个现有付款 ID。

3. **运行 /mp-review — 上线前必须执行。**这是集成流程的 第 6 步，共 7 步。首次付款后，自动检查器会自动验证你的集成。在 /mp-review 通过之前，不要切换到生产凭证（第 7 步）。

你目前处于第 6 步，共 7 步。/mp-review 通过后，只剩下切换到生产凭证这一步。

---

常见问题库

仅渲染与所选产品对应的部分。这些是文档未明确说明的实践陷阱。请保持简短。

checkout-pro

• **始终使用 init_point，不要使用 sandbox_init_point。**Mercado Pago 没有沙盒——只有生产 API。测试时使用测试用户凭证（APP_USR-），而不是不同的 URL。
• currency_id 必须与国家/地区相符（ARS、BRL、MXN、CLP、COP、PEN、UYU）。
• 不要只信任 back_url 查询参数——务必在服务端重新获取付款状态。
• auto_return=approved 需要设置 back_urls.success；否则会被静默忽略。
• external_reference 是你的对账依据——每个 preference/order 都要设置它。

checkout-api

• ⛔ Orders API 需要测试买家用户——如果使用任意电子邮箱，会返回 422 unprocessable_content。测试前运行 /mp-integrate test-setup。这适用于所有国家。
• getCardFormData() 返回 camelCase——字段是 paymentMethodId 和 issuerId，不是 payment_method_id 和 issuer_id。请在服务端进行映射。
• Orders API 的 payment_method 中不允许包含 issuer_id——请从请求载荷中移除，否则会出现 additionalProperties not allowed。
• Checkout API 界面应保持简洁——始终显示卡号、有效期、安全码和持卡人姓名。仅当可信的应用状态尚未提供付款人电子邮箱/身份信息时，才收集这些信息。在 DOM/CardForm 映射中保留 SDK 要求的 issuer、installments 和 identificationType 选择框，但不要在简洁界面中显示；除非商家明确提供分期付款，否则在服务端强制设为 installments: 1。
• total_amount 和 amount 必须是 "10.00"，而不是 "10"——使用 Number(x).toFixed(2)。
• 巴西（MLB）：该产品名为 Checkout Transparente——在 MCP 查询中使用此名称。
• 卡令牌只能使用一次，并会在 7 天后过期。
• 创建付款时始终发送幂等键；不带幂等键重试会导致重复扣款。

bricks

• 后端因变体而异。 card-payment 和 payment 通过 Payments API 创建付款；wallet 在 /checkout/preferences（不带 v1）创建动态偏好；status-screen 只显示已有的 paymentId。
• 始终在 brick 上方显示收费金额。 brick 不会醒目地显示总金额，买家无法看到自己要支付多少。请在容器 div 上方添加 <p>Total: <strong>{currency} {amount}</strong></p>。
• 始终在 UI 中包含三种付款状态。（1）brick 初始化期间以及 onSubmit 运行期间显示加载状态或旋转图标。（2）成功状态，显示付款 ID 和“Payment approved”消息。（3）错误状态，显示可采取行动的消息（“Card declined — try a different card”），而不是原始 API 错误字符串。缺少这些状态，买家就不知道付款是否成功。
• 容器 <div id="..."></div> 必须在调用 bricksBuilder.create(...) 之前存在于 DOM 中。setTimeout 不能解决问题；请使用 onReady，或在 ref 挂载后使用 React useEffect。
• onSubmit 必须返回一个 Promise，并在服务器响应后才完成；返回 void 会导致 brick 永远停留在加载状态。
• 对于 Card Payment Brick：金额由服务器端验证；绝不要信任 brick 回传的金额。
• Wallet Brick 要求买家登录 Mercado Pago；使用测试用户的凭据时，测试用户也视为已登录。
• Status Screen Brick 会处理 3DS 验证挑战的渲染；不要再自行渲染 3DS iframe。
• 广告拦截器（uBlock、AdBlock Plus、Brave shields）会拦截 sdk.mercadopago.com → brick 会触发 FIELDS_SETUP_FAILED，并在不提示的情况下挂载失败。如果开发者反馈“brick 没有显示”，请先检查广告拦截器，再调试代码。
• 借记卡不会显示分期选择器——这是正常行为，不是错误。请确保服务器接受借记卡的 installments: 1，且不要求必须提供选择器字段。
• 绝不要将 preferenceId 硬编码为占位符（例如 <PREFERENCE_ID>、YOUR_PREFERENCE_ID、"preference_id"）：brick 会在不提示的情况下失败。必须始终在服务器上为每个买家会话动态创建 preferenceId。
• 绝不要信任来自浏览器的 Wallet 商品价格。 请发送不透明的购物车／购买 ID，并在调用 Mercado Pago 前，根据可信的服务器端状态重新构建偏好商品和金额。
• 偏好绝不使用版本前缀或路径段。 有效路径必须严格为 /checkout/preferences。
• Status Screen Brick 需要 payment_id——从 POST /v1/payments 响应中提取该值（response.id），并传给 brick。不要传入订单 ID。
• 原生 JavaScript 构建器的生命周期： 保留 bricksBuilder.create() 返回的 controller，并在重建或移除其容器前调用 controller.unmount()。React SDK 组件会自行管理 controller 的生命周期；不要再为它创建第二个 controller。
• back_urls 必须与挂载 brick 的页面处于同一源。 跨域 back_urls 会在不提示的情况下失败——付款后重定向会落到空白页面，且没有任何错误提示。

qr

• 新集成始终使用 Orders API，并设置 type: "qr"；旧版 /instore/... 路由和经过 QR 编码的 Checkout 重定向 URL 都属于脚手架错误。
• 创建订单前，门店和 POS 必须已存在。config.qr.external_pos_id 必须与 POS 的 external_id 完全一致，且该 POS 必须属于创建订单时所用令牌对应的卖家。
• 有效模式为 static、dynamic 和 hybrid。只有 dynamic 和 hybrid 会返回 type_response.qr_data；static 使用创建 POS 时返回的 QR。
• 在本地编码 QR 数据，绝不要发送给第三方图片生成器。轮询订单，并明确处理 created、processed、canceled、expired 和 refunded 状态。处理 QR Orders 的 webhook 使用 orders 主题。要进行真实的成功处理／退款测试，仍需使用买家测试账户扫码；不要臆造 Point /events 模拟器来测试 QR。

Point

• 新集成使用 Orders API，设置 type: "point" 和 config.point.terminal_id；切勿搭建 /point/integration-api/.../payment-intents、type: "instore" 或 config.device.id。
• 如果没有实体硬件，只能在明确启用测试模式后使用标准虚拟终端 NEWLAND_N950__SBX0000001，并通过 /v1/orders/{order_id}/events 模拟每笔订单的结果。它不适用于集成质量评估。
• 实体设备必须与 User ID（而非应用程序）配对，并运行在 PDV 模式下。与错误用户配对的设备会静默拒绝订单。
• 固件更新后，设备可能需要约 2 分钟才能重新上线；不要频繁重试创建订单。
• Point（Orders API）的 Webhook 主题是 orders。旧版 point_integration_wh 主题属于旧版 Point Integration API，切勿用于新集成。

订阅

• 搭建前先选择 with-plan、without-plan-authorized 或 without-plan-pending。不带计划创建的预授权无法事后迁移到计划。
• 切勿暴露手动填写银行卡令牌的字段。已授权合约必须使用 MercadoPago.js 安全令牌化；待处理合约不需要令牌，并会重定向到 init_point。
• 关联的计划 ID 和所有定期条款均由服务端控制。切勿接受来自浏览器的计划 ID、金额、货币或频率。
• 定期扣款失败时会重试；需明确处理 authorized、pending、paused 和 canceled 状态，并通过 GET/Webhook 对账。
• 生产环境中的 back_url 必须使用 HTTPS；HTTP 仅可作为本地开发的备用方案。

市场平台

• Marketplace 是 OAuth 加结账合约，而非独立的 Orders API。应先确定使用 Checkout Pro、Checkout API/Payments 还是 Wallet Brick。
• 使用加密的一次性 OAuth state、完全匹配的已配置重定向 URI、加密的持久化令牌，以及原子化的刷新令牌轮换。切勿暴露或记录卖家令牌。
• 卖家、购物车金额和佣金均应来自可信的服务端状态。切勿接受买家请求中的 seller_id、collector_id、金额或费用。
• Checkout Pro/Wallet 在 /checkout/preferences 中使用 marketplace_fee；Checkout API 在 /v1/payments 中使用 application_fee。Authorization 标头中的卖家 OAuth 令牌决定收款卖家；切勿在付款负载中凭空添加 collector_id。

钱包连接

• 需要 Mercado Pago 商业启用。 如果未明确启用，请先停止，不要更改项目文件。
• 用户必须在 MP 钱包界面中批准关联，不存在静默关联。
• 创建专用的账户关联页面；如果应用程序已有实际的最终结账 CTA，则将其接入该页面。
• 批准码和付款人令牌仅限服务端使用。请在持久化存储中加密付款人令牌，切勿将其暴露给浏览器或写入日志。
• 关联完成后，付款通过 Orders API 使用买家保存的支付方式；不要传递银行卡详细信息、加载 MercadoPago.js 或以 Wallet Brick 代替。
• 使用唯一的幂等键、可信的购买数据，以及匹配且保留两位小数的订单和付款金额。

资金转出

• 当前产品名称为 Payouts。切勿搭建已过时的通用 disbursements 合约，也不要用 Advanced Payments 替代。
• API 合约因国家/地区而异：生成代码前先确认合约，切勿将阿根廷负载用于巴西，反之亦然。
• Payouts 是一项特权级服务端资金转移操作。必须要求操作员授权、可信且持久的指令、已持久化的幂等控制以及审计跟踪；切勿信任来自浏览器的目标或金额。
• 测试调用必须明确启用 Payouts 测试模式并使用官方测试标头。生产环境必须对完全序列化的请求正文进行 Ed25519 签名。
• Accepted、created 和 pending 均不代表最终入账。应通过查询和 Webhook 对返回的资源进行对账。

smartapps

• 需要直接联系 Mercado Pago 团队——SmartApps 不支持自助操作。请先确认开发者已与 MP 签订有效协议，再搭建项目。
• SmartApps 运行于 Point 设备上——代码限制和 API 与服务器 SDK 不同。请始终通过 MCP 查询 SmartApps 专用指南。
• 切勿将 Web 应用改造成 SmartApp。目标必须是 Android；只有在开发者授权此范围后，才能创建独立的 Android 应用/模块。
• SDK 是来自 Mercado Pago 集成套件的私有 AAR。更新前请先征求同意，只使用集成团队确认的最新构件，绝不可替换为公开的 SDK 坐标。
• 静态验证器无法替代使用真实 AAR 进行编译、在开发终端上进行沙盒模拟测试，或 Mercado Pago 认证。

---

此技能不会做什么

• 它不会验证 Webhook。请使用 mp-webhooks 技能（或 /mp-integrate webhook）。
• 它不会创建测试用户。请使用 mp-test-setup 技能（或 /mp-integrate test-setup）。
• 它不会评估集成质量。请使用 mp-review 技能（或 /mp-review）。
• 它不会凭记忆编写代码。代码片段来自按国家/地区获取的官方 llms.txt（第 1 级）、references/products.md（第 2 级）或 MCP search_documentation（第 3 级备用来源）。绝不可仅凭训练数据记忆编写。