SuperAPI AI 工具集

mp-sdks

编程与开发

查看项目

更新于 10-16 14:35

技能介绍

用途

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 项目从零开始

步骤:

  1. 移除 CDN 脚本——删除 <script src="https://sdk.mercadopago.com/js/v2"></script>
  2. 安装包——npm install @mercadopago/sdk-react
  3. 替换初始化——new MercadoPago(key) 改为 <MercadoPagoProvider publicKey={key}>
  4. 替换 Bricks——mp.bricks().create('payment', ...) 改为 <Payment initialization={...} />
  5. 替换回调——callbacks: { onSubmit, onReady, onError } 改为 React props:onSubmit、onReady、onError
  6. 充分测试——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 详情