一. 米大师简介

1.米大师（Midas）为腾讯官方唯一虚拟支付平台。

2.YSDK已经内置了米大师（Midas）支付模块，游戏开发者接入YSDK后，可以通过相应的配置开启米大师的支付功能，并调用YSDK已经封装好的接口，即可快速实现支付能力。目前已支持微信支付（wechat）、QQ钱包（qqwallet）两种支付渠道。

3.米大师（Midas）目前支持直接购买道具（直购模式）、游戏币、游戏币+直接购买道具三种模式，本文重点介绍直购模式，其他支付模式请参考该文档。

二. 直购模式介绍

2.1 计费信息介绍及填写

2.2 计费信息变更

2.3 支付流程示意图

服务器端下单流程：

客户端下单流程：

(1) 成功发货

条件一：在游戏接入平台创建新应用时，在分区配置中配置了回调接口URL，URL用于提供给腾讯后台回调。用户付费成功后，腾讯后台将回调该URL通知业务发货。

条件二：开发者需按照《回调发货URL的协议说明》进行发货URL的开发，收到米大师的回调后必须2s内返回{“ret":0,"msg":"OK"}才认为时发货成功。

(2) 发货失败

由于网络等原因可能回调业务失败，米大师有以下三种重试机制：

微信支付渠道：不退款，24小时内总共会发起15次通知，通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h

QQ钱包：不退款，2小时内重试9次（15s/15s/30s/180s/1800s/1800s/1800s/1800s/3600s）

Q币、Q卡：回调发货失败5分钟后会退款。

三. 直购模式准备工作

1. 填写基本资料

直购模式不需要配置兑换比例，但必须配置回调接口，本环节重点介绍托管类型选择、回调接口配置、米大师证书安装说明；基本信息、分区介绍可参考游戏币模式填写说明。

1.1 托管类型

外部服务器

注：外部服务器，指非腾讯云和腾讯自研的其他服务器，比如阿里云、华为云服务器等。

2. 回调接口

注：沙箱和现网回调接口不可以使用同一个，且多个游戏也不可以使用同一个发货地址。

3.米大师证书下载安装

米大师证书必须先新增沙箱或现网接口后才会显示下载入口，沙箱和现网配置步骤相同，以沙箱环境为例，如下图：

注意：

（1）使用外部托管类型的游戏必须安装米大师证书。

（2）目前腾讯云（DEV）服务器已不支持基础网络，所以使用腾讯云（DEV）服务器的，均需要选择https协议，同时也需要安装下载米大师证书。

（3）直购模式下，腾讯云服务器回调接口和米大师证书下载安装步骤请参考上述步骤。

（4）沙箱和现网的证书不可共用，需各自使用对应环境下载的证书。

（5）多个游戏不可使用同一个米大师证书。

（6）回调发货协议说明请参考米大师文档。

三. 直购模式客户端接入

1. 直购支付流程图

服务器下单流程：

客户端下单流程：

2. 概述

直购模式支持单机和网游游戏。

客户端下单模式是指用户直接通过下述api调用唤起腾讯支付页面引导用户完成付费，用户付费结束后，结果会通过参数重的YSDKPayListener回调给游戏，同时米大师会调用游戏在米大师配置的回调地址发货。

3. 请求参数

4. 请求示例

5. 返回参数

注意事项：

支付不以客户端的结果为准。

四.直购模式服务端下单接入

1. 概述

直购模式分为服务器下订单和客户端下订单两种。 客户端下订单请参考客户端接入

2. 服务端下单模式

服务器下单模式是指游戏应⽤开发者在游戏中调⽤如下接⼝执⾏订单操作，获取到⽀付服务器返回的订单url

现⽹：https://ysdk.qq.com/mpay/buy_goods_m

沙箱：https://ysdktest.qq.com/mpay/buy_goods_m

3. 请求参数

3.1 Cookie参数

注意事项：

cookie里面org_loc的值，需要进行urlencode，如果使用开平提供的 OpenAPI V3.0 SDK 计算签名，org_loc不需要进行urlencode，因为sdk已经在内部做了编码。

session_id中openid为固定的字符串字段，并非登录成功后获取的openid

游客登陆为

session_id="hy_gameid"

session_type="st_dummy"

3.2 请求参数

4. 请求示例

5. 道具直购客户端接口 （服务器下单）

该接口用于通过后台服务器下单的道具直购场景，游戏调用接口以后唤起腾讯支付页面引导用户完成付费，用户付费结束以后，结果会通过参数中的YSDKPayListener回调给游戏，同时米大师会调用游戏在米大师配置的回调地址发货。

5.1 接口声明

5.2 请求示例

5.3 接口调用

6. 返回参数

五.直购模式客户端下单案例

1.前端拉起商品列表

用户登录app后,进入商品购买页面,前端请求app商品列表api接口，获取商品列表信息并展示

2.下单

用户点击'购买'操作,发送给服务端一条当前商品信息,服务端保存该商品的相关订单数据,并返回给前端腾讯米大师支付所需要的请求数据，前端调用米大师支付sdk，发起支付请求

    /**
     * 腾讯应用宝米大师支付下单
     * @param array $params 订单信息
     * @return array
     */
    public static function Pay($params)
    {
        //获取商品内部订单号
        $innerOno = self::genInnerOno(date("Y-m-d H:i:s"), $params['user_id'], $paymentType);
        //生成订单
        $order = new Order();
        $order->order_id = $innerOno;  // 内部订单号
        $order->product_name = $params['name'];  // 商品名称
        $order->number = $params['num'];  // 购买商品个数
        $order->price = $params['price'];  // 商品单价, 1个商品价格
        $order->total_price = $params['total_price'];  // 总的价格
        $order->pay_amount = $params['pay_amount'];  // 应付总额:  实际应该支付的价格= 总金额 - 优惠金额
        $order->count = $params['count'];  // 购买后得到商品对应的产品数量
        $order->status = 0;  // 状态:0 待支付     
        $order->user_id = $params['user_id'];  // 用户游戏ID
        $order->expired_at = $params['expired_at'];  // 过期时间
        $order->created_by = $params['created_by'];  // 创建者
        $order->updated_by = $params['updated_by'];  // 创建者
 
        $result = $order->save();
        if (!$result) {
            $errors = '';
            if ($order->hasErrors()) {
                $tmp = $order->getErrors();
                foreach ($tmp as $rows) {
                    foreach ($rows as $row) {
                        $errors .= $row . '<br/>';
                    }
                }
            }
            throw new \Exception($errors);
        }
        $orderId = $order->id;
        
        //构建vivo支付所需要的数据
        $title = $order->product_name;
        //过滤掉特殊字符
        $title = replaceStr($title);
        $config = Yii::$app->params['tencent.app']; //腾讯应用宝配置
        $price = intval($model->pay_amount * 10);
        //游戏中米大师的appkey,沙箱用沙箱的appkey,现网用现网的appkey.
        $midasAppkey = $config['tx_midas_is_sandbox'] == 1 ? $config['tx_midas_sandbox_app_key'] : $config['tx_midas_now_app_key'];
 
        //构建向应用宝发送的参数
        $data = [
            'iscanchange' => false, //是否可以在拉起的支付页面进行变更
            'zoneid' => 1,  //分区id
            'id' => $model->order_id,  //游戏内自定义的道具id
            'name' => $title,  //道具的名称，支付时会显示在支付页面上
            'desc' => $title,  //道具描述
            'price' => $price,  //道具单价，单价以Q点（角）为单位
            'num' => 1,  //购买数量，在支付页面上不可修改
            'unit' => '个',  //物品单位
            'midasAppkey' => $midasAppkey,  //游戏中米大师的appkey,注：沙箱用沙箱的appkey,现网用现网的appkey.
            'midasExt' => 'midasExt',  //米大师透传参数，会调用发货接口时透传给游戏
            'ysdkExtInfo' => 'ysdkExtInfo',  //YSDK透传参数，会在listener中回调给游戏
        ];
 
        return jsonFail($data);
    }
 
   /**
     * 生成本系统内部订单号, 在向第三方服务商发起支付时需要使用.
     *
     * 下单时的处理流程:
     *   1. 属性 ono 不要赋值, 成功插入(保存)订单.
     *   1. 支付前生成本系统内部订单号, 向第三方发起支付请求.
     *   1. 接收到支付成功回调通知时, 将第三方订单号保存到本次付款的订单的 ono 字段上.
     *
     * 格式: 下单时间+支付方式+ 4位数字修正值. 如 "20150930140041+1+1234".
     * 最大长度 32 个字符. 这也是 wx 可接受的订单号最大长度.
     *
     * @param int $createdAt 订单创建时间戳, 即 下单时间戳.
     * @param int $createdBy 订单创建人 ID, 即 下单会员 ID.
     * @return string
     * @throws \Exception
     */
 
    public static function genInnerOno($createdAt, $createdBy)
    {
        $createdAt = strtotime($createdAt);
        if (1 > $createdAt || 1 > $createdBy) {
            throw new \Exception('参数错误');
        }
 
        // 生成一个修正值, 一定程度上增加订单号的随机性.
        $tmp = intval(substr($createdAt, -4)) + intval(substr($createdBy, -2));
        if (4 < strlen($tmp)) {
            $tmp = substr($tmp, -4);
        }
 
        $tmp = date('YmdHis', $createdAt) . $tmp . rand(100, 900);
        return $tmp;
    }

3. 支付

前端获取服务端返回的支付所需要的请求数据后，拼接支付请求参数，调用米大师支付sdk，发起支付请求

4. 回调操作

前端支付成功后，米大师会请求服务端的回调方法( 三. 直购模式准备工作中的配置步骤)，对支付订单进行校验验签操作，根据验签结果，处理订单业务逻辑

php以yii2框架为参考

    /**
     * 腾讯应用宝支付回调处理: 异步回调操作: 主动请求多次, 用于处理商家订单状态等逻辑操作
     */
    public function actionNotify()
    {
        /获取回调通知数据
        $inBodyArray = $_GET;

        //判断通知请求
        $trans = Yii::$app->db->beginTransaction();
        try {
            //引入米大师SDK
            $dir = Yii::getAlias('@common/lib/tenxun/PHP_SDK_V3.0.9');
            require_once $dir . '/lib/SnsSigCheck.php';
            //签名校验
            $config = Yii::$app->params['tencent.app'];
            //获取AppKey
            $midasAppkey = $config['tx_midas_is_sandbox'] ? $config['tx_midas_sandbox_app_key'] : $config['tx_midas_now_app_key'];
            $checkSign = \SnsSigCheck::verifySig('GET', '/notify', $inBodyArray, $midasAppkey . '&', $inBodyArray['sig']);
            if ($checkSign) { //处理业务逻辑
                $cftid = $inBodyArray["cftid"]; //财付通订单号
                $payitem = $inBodyArray['payitem'];//物品信息
                $payitem = explode("*", $payitem);
                $order_id = $payitem[0]; //
                // 订单状态
                $status = UserOrder::STATUS_BUY;

                //判断订单状态是否已经支付
                $userOrder = UserOrder::find()->where(['status' => $status, 'deal_number' => $innerOno])->exists();
                if ($userOrder) {
                    throw new \Exception('订单已支付');
                }
                // 变更订单属性
                UserOrder::changeAttribute(
                    ['order_id' => $order_id],
                    [
                        'status' => $status,
                        'paid_at' => time(), //支付时间
                        'cftid' => $cftid,
                    ]
                );

                $trans->commit();
                //返回给客户端数据，客户端会根据该结果处理米大师中该订单状态
                $result = [
                    'ret' => 0,
                    'msg' => 'OK',
                ];
            } else {
                throw new \Exception('签名校验失败');
            }
        } catch (\Exception $e) {
            $result = [
                'ret' => -5,
                'msg' => $e->getMessage(),
            ];
         
            $trans->rollBack();
        }
        echo json_encode($result);
    }

5.上面需要使用到的公共方法

/**
 * 操作成功
 * @example1 jsonSuccess();
 */
function jsonSuccess($data = NULL, $message = '操作成功')
{
    header("Content-Type:application/json");
    $json = array();
    $json['code'] = 0;
    $json['data'] = $data;
    $json['message'] = $message;
    $json['request_time'] = now();
    echo Json::encode($json);
    exit();
}

/**
 * 错误信息
 * @example1 jsonFail();
 * @example1 jsonFail("删除失败！");
 * @example2 jsonFail($model->getErrors());
 */
function jsonFail($message = '请求失败', $code = 1, $data = null)
{
    header("Content-Type:application/json");
    $json = array();
    $json['code'] = $code;
    $json['data'] = $data;
    $json['message'] = $message;
    $json['request_time'] = now();
    echo Json::encode($json);
    exit();
}

/**
 * 过滤掉特殊的字符
 * @param $str
 * @param string $replacement
 * @return string|string[]|null
 */
function replaceStr($str, $replacement = '')
{
    $regex = "/\/|\～|\，|\。|\！|\？|\“|\”|\【|\】|\『|\』|\：|\；|\《|\》|\’|\‘|\ |\·|\~|\!|\@|\#|\\$|\%|\^|\&|\*|\(|\)|\_|\+|\{|\}|\:|\<|\>|\?|\[|\]|\,|\.|\/|\;|\'|\`|\-|\=|\\\|\|/";
    $result = preg_replace($regex, $replacement, $str);

    return $result;
}

Yii2 腾讯应用宝米大师相关配置：params-local.php

<?php

return [
     //腾讯应用宝
    'tencent.app' => [
        //腾讯应用平台，米大师沙箱,现网
        'tx_midas_is_sandbox' => 1,
        //腾讯应用平台，米大师沙箱AppKey
        'tx_midas_sandbox_app_key' => 'xxx',
        //腾讯应用平台，米大师现网AppKey
        'tx_midas_now_app_key' => 'xxx',
        'pay_test' => 1, //是否支付测试
        'is_screen_pay' => 0, //是否屏蔽支付
    ],
];

腾讯应用宝米大师支付SDK下载：链接: https://pan.baidu.com/s/1o93e9IkRajVzwwSI1Z3Lkg 提取码: sko1

参考文档：

YSDK介绍：https://wikinew.open.qq.com/index.html#/iwiki/847226339

米大师国内标准版： https://wiki.midas.qq.com/post/index/1/45/82/0

SDK下载文档：https://wikinew.open.qq.com/index.html#/iwiki/877913496