开放平台V2文档

# 支付

微信小游戏提供虚拟充值的能力，用户可以在游戏内下单，进行游戏内道具的购买；本文主要对游戏内的支付能力进行简单概述说明。

# 支付方式

在不同的设备环境中，因相关策略限制，SDK实现支付能力的方式有所区别，如下所示：

支付方式 说明
h5 跳转H5网页支付，适用于Android、iOS、Windows、macOS、微信小游戏开发者工具；仅在上架至SDK官方渠道时支持
midas 游戏内米大师支付，仅适用于Android、Windows、微信小游戏开发者工具；使用米大师支付需要登录《微信公众平台》进行开通，详情请参考《虚拟支付2.0协议签署》文档说明

注意事项

由于微信的策略限制，在iOS设备中，微信小游戏内不能直接进行支付，包括：

  • 在iOS设备中，微信小游戏内无法直接发起虚拟支付（即米大师支付），安卓设备无此限制；
  • 在iOS设备中，使用跳转小程序进行支付时，小程序一旦被封禁，将导致无法充值。

默认情况下，SDK将在Android设备中使用米大师支付，iOS设备中使用跳转H5网页支付；如果Android设备中不想使用米大师支付，相关的米大师开通或配置可忽略；米大师支付需要相应的版号，若游戏没有版号，建议直接使用跳转H5网页支付。

如果游戏内支付需对Android或iOS等设备做区分处理，请自行参阅微信开放接口进行判断，或者根据 sdkInstance.system.platform 返回值进行判断。

Platform 枚举值 说明
android Android微信
ios iOS微信（包含 iPhone、iPad）
windows Windows微信
mac macOS微信
devtools 微信开发者工具

# 支付流程

不同的支付方式在游戏内所表现出的支付流程不尽相同，请参考如下说明：

支付方式 支付流程
h5 点击购买按钮 > 调用支付接口 > 向用户弹出“即将进入xxxx客服会话” > 确认并进入客服会话 > 点击并发送客服会话窗口右下角浮动卡片 > 客服自动回复H5网页支付链接 > 点击链接进入H5网页支付页面 > 完成支付
midas 点击购买按钮 > 调用支付接口 > 向用户弹出收银台 > 完成支付

注意事项

若使用了 h5 跳转H5网页支付方式，且用户进入客服会话并发送会话窗口右下角浮动卡片后，客服没有自动回复充值链接，请咨询SDK服务端开发：陈肖军！

# 准备事项

# 添加安全域名

根据游戏的发行企业或主体，登录《微信公众平台》 (opens new window)后台，进入“开发 > 开发管理 > 开发设置”，在“服务器域名（request 合法域名）”一栏中添加相应的安全域名，详见前文《准备工作 > 添加安全域名》介绍。

# 开通虚拟支付（米大师支付）

登录《微信公众平台》 (opens new window)后台，进入“功能 > 虚拟支付”，申请开通虚拟支付（米大师支付）能力，若不使用该支付方式，此项可忽略，详情请参考《虚拟支付2.0协议签署》 (opens new window)文档说明，若有其他疑问请咨询SDK开放平台开发人员。

虚拟支付开通后，CP需要向SDK开放平台开发人员提供如下信息：

参数 说明
gameAppId 于微信公众平台注册游戏时生成的 AppID
gameAppKey 于微信公众平台注册游戏时生成的 AppKey
appId 于SDK开放平台注册游戏时生成的 AppID
offerId 虚拟支付的应用 ID；可登录《微信公众平台》后台，进入“功能 > 虚拟支付 > 基本配置 > 基础配置”栏目中查看
appKey 虚拟支付的 appKey（沙箱/现网）；可登录《微信公众平台》后台，进入“功能 > 虚拟支付 > 基本配置 > 基础配置”栏目中查看
rate 虚拟支付的支付比例，用于扣除游戏币；例如：后台配置为 1:10，则 rate 为 10，表示1人民币=10游戏币；可登录《微信公众平台》后台，进入“功能 > 虚拟支付 > 基本配置 > 游戏币配置”栏目中查看

# 游戏道具价格设置

针对不同的支付方式，游戏在设置道具价格时，需要注意以下区别：

支付方式 充值额度
h5 使用跳转H5网页支付时，支持任意金额
midas 使用游戏内米大师支付时，请务必根据微信小游戏官方API的限定价格等级进行设置

综合上表所示，如果游戏同时使用了 h5、midas 两种支付方式，那么需按照最小兼容原则设置游戏道具价格，即根据微信小游戏官方API的限定价格等级 (opens new window)进行设置！

# 配置支付回调接口

游戏服务器需按照《服务端对接 > 登录支付 > 支付回调》文档要求，向相关运营人员提供支付回调接口，并由运营人员配置至SDK开放平台后台，用于在用户支付成功后通知游戏发放相应购买商品！

# 接口说明

用于游戏内发起支付，仅在登录成功后可用。

sdkInstance.pay(options, settings?);

最低基础库版本要求

  • 使用跳转H5网页支付时，若用户客户端基础库版本低于 2.0.3，调用 sdkInstance.pay(options, settings?) 接口将中断用户当前操作并弹出升级提示，不会报错！
  • 使用游戏内米大师支付时，则不受用户客户端基础库版本影响！

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
options object 是 -- 支付参数
    options.cardMessageTitle string 否 -- 进入微信客服会话时，会话窗口右下角浮动卡片的标题，仅在使用跳转H5网页支付时必填；建议填写当前所购商品的中文名称，如：我要充值68元首充礼包
    options.cardMessageImage string 否 -- 进入微信客服会话时，会话窗口右下角浮动卡片的图片路径，仅在使用跳转H5网页支付时必填；建议设计制作一张引导玩家充值的图片并上传至CDN，引用图片CDN地址即可，点击查看图片样例
    options.areaId string / number 否 1 游戏大区ID，若游戏无大区概念，可不填，默认值为 1，表示初始大区编号
    options.areaName string 否 1 游戏大区名称，若游戏无大区概念，可不填，默认值为 1
    options.roleId string / number 否 同 accountId 角色ID，若游戏无角色概念，可不填，默认值同 accountId 账号ID
    options.roleName string 否 -- 角色昵称
    options.roleLevel number 否 1 角色等级，若游戏无角色及等级概念，可填关卡等级或不填，默认值为 1
    options.itemId string 是 -- 商品ID
    options.itemName string 是 -- 商品名称
    options.itemNum number 否 1 商品数量，一般固定传 1
    options.itemPrice number 是 -- 商品单价，单位为分！！！
    options.currency string 否 CNY 货币类型，默认为 CNY
    options.rate number 是 -- 游戏币兑换汇率，用于计算游戏币购买数量；例如：后台配置为 1:10，则 rate 为 10；可登录《微信公众平台》后台，进入“功能 > 虚拟支付 > 基本配置 > 游戏币配置”栏目中查看
    options.memo string 否 -- 透传参数，支付完成后，SDK服务器将通过支付回调原样返回给游戏服务器
    options.remark string 否 -- 备用透传参数
    options.success function 否 -- 接口调用成功的回调函数（注意，该回调函数被触发时，仅表示当前接口调用成功，并非代表用户实际完成了支付流程，支付且发货成功应以游戏服务端下发通知为准）
    options.fail function 否 -- 接口调用失败的回调函数
    options.complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用
settings object 否 -- 支付方式配置（注意，该参数仅在上架至SDK官方渠道时支持）
    settings.android string 否 midas Android设备中使用的支付方式，可选值为 h5、midas
    settings.ios string 否 h5 iOS设备中使用的支付方式，可选值为 h5
    settings.windows string 否 midas Windows设备中的支付方式，可选值为 h5、midas
    settings.mac string 否 h5 macOS设备中使用的支付方式，可选值为 h5（暂不支持打开小游戏，此选项可忽略）
    settings.devtools string 否 midas 微信小游戏开发者工具中使用的支付方式，可选值为 h5、midas

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 使用跳转H5网页支付，若用户客户端基础库版本不低于2.0.3，调用此接口将中断用户当前操作并弹出升级提示，不会报错！
// 使用游戏内米大师支付时，则不受用户客户端基础库版本影响，但不支持iOS或Mac设备
sdkInstance.pay({
  cardMessageTitle: "我要购买60钻石", // 该选项仅在使用跳转H5网页支付时必填，一般此参数必填，因iOS设备仅支持跳转H5网页支付
  cardMessageImage: "http://static.m3guo.com/om/minigame/wx/payment.png", // 该选项仅在使用跳转H5网页支付时必填，一般此参数必填，因iOS设备仅支持跳转H5网页支付
  areaId: 1001,
  areaName: "1区",
  roleId: "123456",
  roleName: "小朋友",
  roleLevel: 1,
  itemId: "com.dh.test",
  itemName: "60钻石",
  itemNum: 1, // 一般固定传1
  itemPrice: 600, // 商品单价单位为分，请注意换算！例如此示例中的600表示600分，即6元
  currency: "CNY",
  rate: 10,
  memo: "123456789123456789", // 透传参数，字符串类型；支付完成后，SDK服务器将通过支付回调原样返回给游戏服务器；这里演示透传游戏业务订单号
  remark: "", // 备用透传参数
  success: function(response) {
    // 该回调函数被触发时，仅表示当前接口调用成功，并非代表用户实际完成了支付流程，支付且发货成功应以游戏服务端下发通知为准
    console.log(response);
  },
  fail: function(error) {
    // 此处返回接口调用失败的错误信息，error.code为cancel时，表示用户主动点击了取消按钮，此时可以不向用户弹出提示
    if (error.code == "cancel") {
      return;
    }

    // 此处可向用户弹出接口返回的错误消息或统一弹出“支付失败”
    sdkInstance.modal.message(error.message);
  },
  complete: function(result) {
    // do something here...
  }
}, {
  android: "midas", // 此处表示Android设备中使用米大师支付
  ios: "h5", // 此处表示iOS设备中使用跳转H5网页支付
  windows: "midas", // 此处表示Windows微信中使用米大师支付
  devtools: "midas" // 此处表示微信小游戏开发者工具中使用米大师支付
});

# 支付回调

游戏服务器需按照《服务端对接 > 登录支付 > 支付回调》文档要求，向相关运营人员提供支付回调接口，并由运营人员配置至SDK开放平台后台，用于在用户支付成功后通知游戏发放相应购买商品！

注意事项

若有接口方面疑问，请咨询SDK服务端开发：陈肖军！

Last Updated: 2025/2/13 14:43:58

← 广告 →