小游戏礼物索要接入指南

此功能为beta版,暂仅支持Android用户发起索要及支付。

基础库版本

2.11.0及以上支持小游戏礼物索要能力.

发起索要

通过调用wx.requestMidasFriendPayment即可发起一次礼物索要请求,请求参数与米大师支付wx.requestMidasPayment类似,需要额外传入唯一的游戏业务单号outTradeNo用于订单关联和去重。

玩家成功发起索要后,会自动唤起微信通讯录,玩家可将礼物索要链接发送给好友和微信群。

收到礼物索要链接的微信用户可点击链接进行支付。

接口参数说明

wx.requestMidasFriendPayment

时序图

用户->游戏: 点击发起索要
游戏->开发者后台: 创建业务索要单
开发者后台-->游戏: 返回业务索要单号及下单参数
游戏->游戏: wx.requestMidasFriendPayment
游戏-->用户: 分享索要单
游戏->开发者后台: 传递加密数据
开发者后台->开发者后台: 解密得到系统索要单号并记录

image.png

示例代码

wx.requestMidasFriendPayment({
  mode: 'game',
  env: 0,
  offerId: 'xxxxxxxx',
  currencyType: 'CNY',
  buyQuantity: 10,
  platform: 'android',
  zoneId: '1',
  outTradeNo: 'xxxxxxxx',  // 游戏业务单号
  nonceStr: 'xxxxxxxx',
  timeStamp: 1585212938,
  signature: 'xxxxxxxx',
  success(res) {
    console.log(res.encryptedData) // 加密数据,包含微信索要单号
    console.log(res.iv)            // 加密算法的初始向量
    console.log(res.cloudID)       // 敏感数据对应的云ID
  },
  fail(err) {
    console.log(err.errCode)
    console.log(err.errMsg)
  }
})

注意事项

  1. 每个outTradeNo只能使用一次,重复用于创建不同索要单时,接口会报错;开发者需合理利用outTradeNo的去重能力,避免玩家发起多次索要导致多买
  2. 接口填写创建过的索要单参数,可重新拉起索要分享;如果创建过的索要单状态是已支付/已超时,不可重新拉起索要分享,接口会返回特定错误码
  3. 微信索要单有效期为24小时

签名算法

签名算法为:

signature = hmac_sha256([appId, mode, ... , nonceStr, timeStamp].sort().join(''), sessionKey)

具体来说,这个算法分为几个步骤:

  1. 将所有接口传入的参数(除了signature之外)的值表示成字符串形式,对值按照字典序排序;
  2. 将排好序的多个字符串拼接在一起;
  3. 使用session_key作为key,使用hmac_sha256算法对步骤2中的结果字符串做计算,所得结果即为signature

解密结果

解密算法详细见加密数据解密算法

示例结果

{
  "outTradeNo": "xxxxxxxx",
  "orderNo": "PBgAAHMjeOhixxxx",
  "watermark": {
    "timestamp": 1585537091,
    "appid": "wx7a727ff7d940xxxx"
  }
}

索要成功消息

微信用户支付成功后,微信平台会调用米大师充值游戏币,充值成功后,会向开发者后台推送索要成功消息。消息推送接入方法详见 消息推送 开发者后台需要接收处理,执行发货逻辑,并按文档规范返回应答(空串或"success")。

索要功能支持2类场景:

  1. 索要米大师游戏币 索要成功消息通知时,微信已确保发起方的米大师游戏币充值完成,游戏侧理论上无需再做任何发货动作。
  2. 索要游戏内道具 索要成功消息通知时,微信已确保发起方的米大师游戏币充值完成(同1),游戏侧需要扣减相应的米大师游戏币,并换成游戏内道具。 游戏内道具由开发者自由定义,可以为任意的一种或多种物品。

时序图

用户->微信后台: 支付成功
微信后台->开发者后台: 索要成功消息
开发者后台->微信后台: 查询用户余额
微信后台-->开发者后台: 查询成功
开发者后台->微信后台: 扣除余额
微信后台-->开发者后台: 扣除成功
开发者后台->开发者后台: 发放道具
开发者后台-->微信后台: 处理成功

image.png

示例消息

<xml>
  <ToUserName><![CDATA[gh_31b2a1c7xxxx]]></ToUserName>
  <FromUserName><![CDATA[oUrsf0TSXNtiZjP7JL9UUFiGxxxx]]></FromUserName>
  <CreateTime>1584075435</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[minigame_ask_order_deliver]]></Event>
  <MiniGame>
    <BusiDeliverCallbackData>
      <outTradeNo><![CDATA[xxxxxxxx]]></outTradeNo>
      <orderNo><![CDATA[PBgAAHMjeOhixxxx]]></orderNo>
      <appid><![CDATA[wx7a727ff7d940xxxx]]></appid>
      <openid><![CDATA[oUrsf0SMlbE3YH2hnlEhO03Zxxxx]]></openid>
      <amount>100</amount>
      <zoneId><![CDATA[1]]></zoneId>
      <env>0</env>
      <payTime>1584067989</payTime>
    </BusiDeliverCallbackData>
  </MiniGame>
</xml>

注意事项

  1. 同样的通知可能会多次发送给开发者后台,系统必须能够正确处理重复的通知。
  2. 后台通知交互时,如果微信收到开发者后台的应答不符合规范或超时,微信会判定本次通知失败,重新发送通知,直到成功为止(在通知一直不成功的情况下,微信总共会发起多次通知,通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m),但微信不保证通知最终一定能成功。
  3. 在索要单状态不明或者没有收到索要成功结果通知的情况下,建议开发者后台主动调用【索要单查询】接口确认订单状态。
  4. 当收到通知进行处理时,首先检查对应业务数据的状态,判断该通知是否已经处理过,如果没有处理过再进行处理,如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。

字段说明

字段名 说明
ToUserName 小游戏原始id
FromUserName 固定取值,可忽略
CreateTime 消息时间
MsgType 消息类型,取值event
Event 消息名称,取值minigame_ask_order_deliver
outTradeNo 游戏业务单号
orderNo 微信索要单号
appid 小游戏appid
openid 索要单下单用户openid
amount 金额(单位分)
zoneId 米大师发货分区
env 米大师环境
payTime 支付时间

索要单查询

第三方后台可以通过 https 调用索要单查询相关后台接口

需要调用查询接口的情况:

  1. 当后台、网络、服务器等出现异常,最终未接收到索要成功消息
  2. 其他异常错误时,可查询比对确认索要单信息是否一致