用途
mp-sdks 是 Mercado Pago 官方提供的 SDK 层参考技能,用于解决与支付 SDK 选型、安装、初始化、迁移和平台兼容性相关的问题。它关注的是 SDK 本身,而不是具体产品集成流程。若开发者询问 Checkout Pro、Bricks、QR 等产品流程,应使用对应的产品技能;产品技能描述集成流程,本技能描述 SDK 层。
覆盖的产品
- 服务端 SDK:Node.js、Python、Java、PHP、Ruby、.NET、Go
- Web 客户端:MercadoPago.js(原生 JS)、React SDK(@mercadopago/sdk-react)
- 移动原生:iOS(Swift)、Android(Kotlin/Java)
- GitHub 组织:https://github.com/mercadopago
适用时机
- SDK 选择:“我应该用哪个 SDK?”
- SDK 安装与初始化
- SDK 迁移(例如从 MercadoPago.js 迁移到 React SDK)
- 平台兼容性问题
- 移动 SDK 的能力与限制
决策树:该选哪个 SDK
- 服务端后端?按语言选择:Node.js、Python、Java、PHP、Ruby、.NET、Go(安装命令见 agent SDK Installation Reference)
- Web 前端——原生 JS 或服务端渲染?使用 MercadoPago.js(CDN 脚本)
- Web 前端——React?使用 @mercadopago/sdk-react(npm 包)
- iOS 原生(Swift/SwiftUI)?使用 sdk-ios,通过 Swift Package Manager
- Android 原生(Kotlin/Java)?使用 sdk-android,通过 Gradle
- React Native?无官方 SDK。Bricks 使用 WebView,或使用服务端 tokenization。
- Flutter?无官方 SDK。使用服务端 tokenization + 自定义 UI。
MercadoPago.js
- 仅从 CDN 加载:
<script src="https://sdk.mercadopago.com/js/v2"></script> - 切勿自托管。CDN 版本负责 PCI 合规并自动更新。
- 初始化:
const mp = new MercadoPago('PUBLIC_KEY')——使用 PUBLIC key,而非 access token。 - 提供:Bricks(
mp.bricks())、Card Form(mp.cardForm())、Card Token(mp.createCardToken()) - 使用场景:Checkout Bricks、卡 tokenization、支付方式选择
React SDK
- 安装:
npm install @mercadopago/sdk-react - 封装 MercadoPago.js——不要再加载 CDN 脚本,两者会冲突。
- 初始化:
<MercadoPagoProvider publicKey="PUBLIC_KEY">包装组件 - 组件:
<Payment>、<Wallet>、<CardPayment>、<StatusScreen> - 要求:React 16.8+(支持 hooks)
- 使用场景:与 MercadoPago.js 相同,但提供 React 组件 API
iOS SDK
- 安装:Swift Package Manager——https://github.com/mercadopago/sdk-ios
- 初始化:配置 publicKey 与 country/locale
- 支持:卡 tokenization、支付方式选择
- 不支持:渲染 Bricks(仅 Web)、完整结账 UI
- 最低 iOS 版本:请查看仓库当前要求
Android SDK
- 安装:来自 github.com/mercadopago 的 Gradle 依赖
- 初始化:配置 publicKey 与 country
- 支持:卡 tokenization、支付方式选择
- 不支持:渲染 Bricks(仅 Web)、完整结账 UI
- 最低 Android 版本:请查看仓库当前要求
迁移:MercadoPago.js 到 React SDK
何时迁移:
- 项目已基于 React,希望用组件 API 代替命令式 JS
- 新建 React 项目从零开始
步骤:
- 移除 CDN 脚本——删除
<script src="https://sdk.mercadopago.com/js/v2"></script> - 安装包——
npm install @mercadopago/sdk-react - 替换初始化——
new MercadoPago(key)改为<MercadoPagoProvider publicKey={key}> - 替换 Bricks——
mp.bricks().create('payment', ...)改为<Payment initialization={...} /> - 替换回调——
callbacks: { onSubmit, onReady, onError }改为 React props:onSubmit、onReady、onError - 充分测试——CDN 与 npm 封装之间的底层 MercadoPago.js 版本可能不同
注意事项
- MercadoPago.js 必须从 CDN 加载——它不作为 npm 包直接 import。React SDK 在内部封装了它。
- React SDK 与 MercadoPago.js CDN 不能共存——同时加载会导致重复初始化错误。
- iOS 与 Android SDK 仅支持 tokenization——不渲染 Bricks 或结账 UI。移动端结账 UI 请使用指向 Checkout Pro 或 Bricks 的 WebView。
- React Native 与 Flutter 无官方 SDK——使用服务端流程或基于 WebView 的方案。
- Go SDK 较新——可能尚未支持 Node/Python/Java SDK 的全部功能。请查看仓库当前能力。
- 所有客户端 SDK 使用 PUBLIC key——切勿在前端或移动端代码中暴露 access token。
- 服务端 SDK 使用 ACCESS TOKEN——从环境变量加载,切勿硬编码。
可从 MCP 获取
- 当前 SDK 版本与变更日志
- 各语言的 SDK 初始化代码
- 各 SDK 的可用方法与能力
可从文档获取
{DOMAIN}/developers/{LANG}/docs/sdks-library/landing—— SDK 概览与下载{DOMAIN}/developers/{LANG}/docs/sdks-library/client-side—— MercadoPago.js 与 React SDK 详情