# 小游戏礼物索要接入指南

该能力已废弃

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

# 基础库版本

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

# 发起索要

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

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

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

# 接口参数说明

wx.requestMidasFriendPayment

# 时序图

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

# 示例代码

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），游戏侧需要扣减相应的米大师游戏币，并换成游戏内道具。 游戏内道具由开发者自由定义，可以为任意的一种或多种物品。

# 时序图

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

# 示例消息

<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. 当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

# 字段说明

# 索要单查询

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

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

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