小游戏支付

小游戏支付提供玩家在小游戏中购买道具的能力

业务流程

虚拟支付 小游戏支付 - 图1

主要的流程：1、小程序内调用登录接口，获取到用户的openid2、开发者 server调用下单接口4、开发者 server接收支付通知

开通小游戏支付

上架道具

开发者需要在QQ小程序开发者管理端虚拟支付 小游戏支付 - 图2上架道具

预下单

本接口应在服务器端调用，详细说明参见服务端API。

玩家购买道具前，开发者需要通过后台接口进行预下单

  1. POST  https://api.q.qq.com/api/json/openApiPay/GamePrePay?access_token=ACCESS_TOKEN

请求参数

属性类型默认值必填说明
openidstring是用户唯一标识符
appidstring是小程序 appId
tsnumber是UNIX 时间戳，单位是秒
zoneidstring是游戏服务器大区id,zoneId ="1"
pfstring是平台 安卓：qq_m_qq-2001-android-2011
user_ipstring否用户外网 IP， 不参与计算签名
amtnumber是扣除游戏币数量，不能为 0
bill_nostring是订单号，业务需要保证全局唯一；相同的订单号不会重复扣款。长度不超过63，只能是数字、大小写字母-
goodidstring是在开发者管理端上架道具的id
good_numint是要购买的道具数量
app_remarkstring否备注信息，如果不为空，通知发货是会回传
sigstring是以上参数（"user_ip"字段除外，含可选最多11个）+uri+session_key，用 HMAC-SHA256签名
access_tokenstring是接口调用凭证

返回值

Object

返回的 JSON 数据包

属性类型说明
errcodenumber错误码
errmsgstring错误信息
prepayIdstring订单号，有效期是 48 小时

errcode 的合法值

值说明
0请求成功
-1系统繁忙，此时请开发者稍候再试
-3000access_token 校验失败，access_token需要放在url中
90011sig签名错误
90012订单已存在
90017没有调用接口的权限
90018参数错误

POST 数据格式：JSON

  1. {
  2.     "openid":"55107C3B8501CD7CBD90AEE4626E6D17",
  3.     "appid":"1107981003",
  4.     "ts":1507530737,
  5.     "zone_id":"1",
  6.     "pf":"qq_m_qq-2001-android-2011",
  7.     "amt":10,
  8.     "goodid":"43",
  9.     "good_num":1,
  10.     "bill_no":"69ae13a3a87f2551109a2ed26bc704201f56d664",
  11.     "app_remark":"xxxxx",
  12.     "sig":"38181bd0acf24eda203655a3be9f2e42b62d4fcf1c1de61a98b0573d13531449"
  13. }

计算签名

  • 请求方法： POST

  • 下单url中的path（/api/json/openApiPay/GamePrePay）部分，做标准的url Encoding, 标准请参考《URL Encoding虚拟支付 小游戏支付 - 图3》

  • 请求参数按字典排序，并用"&"拼接, 注意空字段不参与排序

  1. amt=10&app_remark=xxxxx&appid=1107981003&bill_no=69ae13a3a87f2551109a2ed26bc704201f56d664&good_num=1&goodid=43&openid=55107C3B8501CD7CBD90AEE4626E6D17&pf=qq_m_qq-2001-android-2011&ts=1507530737&zone_id=1
  • 拼接session_key，用户登录时开发者后台可以通过code2session接口获取到
  1. session_key=VUNQZ0hRYURxNlZZbmNOZw==
  • 签名前的字符串如下图
  1. POST&%2Fapi%2Fjson%2FopenApiPay%2FGamePrePay&amt=10&app_remark=xxxxx&appid=1107981003&bill_no=69ae13a3a87f2551109a2ed26bc704201f56d664&good_num=1&goodid=43&openid=55107C3B8501CD7CBD90AEE4626E6D17&pf=qq_m_qq-2001-android-2011&ts=1507530737&zone_id=1&session_key=VUNQZ0hRYURxNlZZbmNOZw==
  • HMAC-SHA256得到的签名结果
  1. $h = hash_hmac('sha256', 'POST&%2Fapi%2Fjson%2FopenApiPay%2FGamePrePay&amt=10&app_remark=xxxxx&appid=1107981003&bill_no=69ae13a3a87f2551109a2ed26bc704201f56d664&good_num=1&goodid=43&openid=55107C3B8501CD7CBD90AEE4626E6D17&pf=qq_m_qq-2001-android-2011&ts=1507530737&zone_id=1&session_key=VUNQZ0hRYURxNlZZbmNOZw==', 'VUNQZ0hRYURxNlZZbmNOZw==', true);
  2. var_dump(bin2hex($h));
  4. 签名：
  5. 38181bd0acf24eda203655a3be9f2e42b62d4fcf1c1de61a98b0573d13531449

通知发放道具

用户支付完成，QQ小程序平台会调用开发者在管理端虚拟支付 小游戏支付 - 图4配置的回调接口，通知开发者给游戏玩家发放道具

请求参数

属性类型默认值必填说明
openidstring是用户唯一标识符
billnostring是订单号，业务需要保证全局唯一；相同的订单号不会重复扣款。长度不超过63，只能是数字、大小写字母-
amtnumber是扣除游戏币数量，不能为 0
tsnumber是UNIX 时间戳，单位是秒
app_remarkstring否备注信息，如果为空，不参与计算签名
sigstring是以上所有参数（含可选最多11个）+appsecret HMAC-SHA256签名

回调地址

这里的回调地址是示例，以开发者在管理端虚拟支付 小游戏支付 - 图5配置的为准

  1.   http://test.com/pay/callback

POST 数据格式：JSON

  • app_remark字段为空时，回调消息如下：
  1. {
  2.   "openid": "55107C3B8501CD7CBD90AEE4626E6D17",
  3.   "bill_no":"BillNo_123",
  4.   "amt":123,
  5.   "ts":1553322984,
  6.   "sig": "1d7d3b724601a0b55a43e03f140ce55322401fedd359b1ea1dfc96a02f6e6f36"
  7. }
  • app_remark字段不空时，回调消息如下：
  1. {
  2.   "openid": "55107C3B8501CD7CBD90AEE4626E6D17",
  3.   "bill_no":"BillNo_123",
  4.   "amt":123,
  5.   "ts":1553322984,
  6.   "app_remark":"xxxxx",
  7.   "sig": "1d7d3b724601a0b55a43e03f140ce55322401fedd359b1ea1dfc96a02f6e6f36"
  8. }

签名

为了确保，QQ会对明文数据进行签名。开发者可以根据业务需要对数据包进行签名校验，确保数据的完整性。

  • 用户的 AppSecret：
  1. HyVFkGl5F5OQWJZZaNzBBg==
  • 用于签名的字符串为：对开发者在管理端虚拟支付 小游戏支付 - 图6配置回调url中的path部分，做标准的url Encoding, 标准请参考《URL Encoding虚拟支付 小游戏支付 - 图7》
  1. strPath=url.QueryEscape("/pay/callback")   // 这里要替换成开发者在管理端配置的链接

计算签名时，没有值的参数不参与签名，所有参与签名的参数按字典序排序，这里以app_remark为空时的回调签名为例，app_remark不空时，需要参与签名

  1. strData="POST&"+strPath+"&amt=123&bill_no=BillNo_123&openid=55107C3B8501CD7CBD90AEE4626E6D17&ts=1553322984&AppSecret=HyVFkGl5F5OQWJZZaNzBBg=="
  1. // 计算签名前的字符串：
  2. POST&%2Fpay%2Fcallback&amt=123&bill_no=BillNo_123&openid=55107C3B8501CD7CBD90AEE4626E6D17&ts=1553322984&AppSecret=HyVFkGl5F5OQWJZZaNzBBg==
  • hmac使用sha256算法得到的结果为
  1. 计算得到的签名: 
  2. f749f67b751fa80f27ddc0b7c8d2821aeda162ea22b323cd64a2c8056c2736f0
  • PHP示例
  1. $h = hash_hmac('sha256', 'POST&%2Fpay%2Fcallback&amt=123&bill_no=BillNo_123&openid=55107C3B8501CD7CBD90AEE4626E6D17&ts=1553322984&AppSecret=HyVFkGl5F5OQWJZZaNzBBg==', 'HyVFkGl5F5OQWJZZaNzBBg==', true);
  2. var_dump(bin2hex($h));

返回值

回调接口需要返回一个json

属性类型默认值必填说明
codenumber是code等于0，表示成功，其他是失败
msgstring是错误描述
  1. {
  2.   "code":0,
  3.   "msg":""
  4. }

查询支付状态

本接口应在服务器端调用，详细说明参见服务端API。

玩家下单购买道具后，如果开发商没有收到支付支付通知，可以通过这个接口查询支付结果

  1. POST  https://api.q.qq.com/api/json/openApiPay/CheckGamePay?access_token=ACCESS_TOKEN

请求参数

属性类型默认值必填说明
openidstring是用户唯一标识符
appidstring是小程序 appId
prepayidstring是预订单号，有效期是 48 小时
bill_nostring是订单号，业务需要保证全局唯一；相同的订单号不会重复扣款。长度不超过63，只能是数字、大小写字母-
sigstring是以上参数（"user_ip"字段除外，含可选最多11个）+uri+session_key，用 HMAC-SHA256签名
access_tokenstring是接口调用凭证

返回值

Object

返回的 JSON 数据包

属性类型说明
errcodenumber错误码
errmsgstring错误信息
pay_statenumber支付状态: 0： 未支付, 1: 已支付
pay_timenumber支付时间戳(单位秒)
app_remarkstring

errcode 的合法值

值说明
0请求成功
-1系统繁忙，此时请开发者稍候再试
-3000access_token 校验失败，access_token需要放在url中
90011sig签名错误

POST 数据格式：JSON

  1. {
  2.     "openid":"55107C3B8501CD7CBD90AEE4626E6D17",
  3.     "appid":"1107981003",
  4.     "bill_no":"69ae13a3a87f2551109a2ed26bc704201f56d664",
  5.     "prepay_id":"beaf257883b098007ca821e1c59f7f7a",
  6.     "sig":"66494923186839a01bd85d528260daabeb507a6a28e5934335dd4ef9cca894f0",
  7. }

计算签名

  • 请求方法： POST

  • 查询url中的path（/api/json/openApiPay/CheckGamePay）部分，做标准的url Encoding, 标准请参考《URL Encoding虚拟支付 小游戏支付 - 图8》

  • 请求参数按字典排序，并用"&"拼接, 注意空字段不参与排序

  1. appid=1107981003&bill_no=69ae13a3a87f2551109a2ed26bc704201f56d664&openid=55107C3B8501CD7CBD90AEE4626E6D17&prepay_id=beaf257883b098007ca821e1c59f7f7a
  • 拼接session_key，用户登录时开发者后台可以通过code2session接口获取到
  1. session_key=VUNQZ0hRYURxNlZZbmNOZw==
  • 签名前的字符串如下图
  1. POST&%2Fapi%2Fjson%2FopenApiPay%2FCheckGamePay&appid=1107981003&bill_no=69ae13a3a87f2551109a2ed26bc704201f56d664&openid=55107C3B8501CD7CBD90AEE4626E6D17&prepay_id=beaf257883b098007ca821e1c59f7f7a&session_key=VUNQZ0hRYURxNlZZbmNOZw==
  • HMAC-SHA256得到的签名结果
  1. $h = hash_hmac('sha256', 'POST&%2Fapi%2Fjson%2FopenApiPay%2FCheckGamePay&appid=1107981003&bill_no=69ae13a3a87f2551109a2ed26bc704201f56d664&openid=55107C3B8501CD7CBD90AEE4626E6D17&prepay_id=beaf257883b098007ca821e1c59f7f7a&session_key=VUNQZ0hRYURxNlZZbmNOZw==')
  2. var_dump(bin2hex($h));
  4. 签名：
  5. 66494923186839a01bd85d528260daabeb507a6a28e5934335dd4ef9cca894f0

查询余额

本接口应在服务器端调用，详细说明参见服务端API。

  1. POST  https://api.q.qq.com/api/json/openApiPay/GetBalance?access_token=ACCESS_TOKEN

请求参数

属性类型默认值必填说明
openidstring是用户唯一标识符
appidstring是小程序 appId
sigstring是以上参数（"user_ip"字段除外，含可选最多11个）+uri+session_key，用 HMAC-SHA256签名
access_tokenstring是接口调用凭证

返回值

Object

返回的 JSON 数据包

属性类型说明
errcodenumber错误码
errmsgstring错误信息
remaindernumber金币余额

errcode 的合法值

值说明
0请求成功
-1系统繁忙，此时请开发者稍候再试
-3000access_token 校验失败，access_token需要放在url中
90011sig签名错误

POST 数据格式：JSON

  1. {
  2.     "openid":"55107C3B8501CD7CBD90AEE4626E6D17",
  3.     "appid":"1107981003",
  4.     "sig":"9a721574bbf7fbfc68f15edd7e9cc355d6a95e2d946ecd4e04b708c4206665b4",
  5. }

计算签名

  • 请求方法： POST

  • 下单url中的path（/api/json/openApiPay/GetBalance）部分，做标准的url Encoding, 标准请参考《URL Encoding虚拟支付 小游戏支付 - 图9》

  • 请求参数按字典排序，并用"&"拼接, 注意空字段不参与排序

  1. appid=1107981003&openid=55107C3B8501CD7CBD90AEE4626E6D17
  • 拼接session_key，用户登录时开发者后台可以通过code2session接口获取到
  1. session_key=VUNQZ0hRYURxNlZZbmNOZw==
  • 签名前的字符串如下图
  1. POST&%2Fapi%2Fjson%2FopenApiPay%2FCheckGamePay&appid=1107981003&bill_no=69ae13a3a87f2551109a2ed26bc704201f56d664&openid=55107C3B8501CD7CBD90AEE4626E6D17&prepay_id=beaf257883b098007ca821e1c59f7f7a&session_key=VUNQZ0hRYURxNlZZbmNOZw==
  • HMAC-SHA256得到的签名结果
  1. $h = hash_hmac('sha256', 'POST&%2Fapi%2Fjson%2FopenApiPay%2FCheckGamePay&appid=1107981003&bill_no=69ae13a3a87f2551109a2ed26bc704201f56d664&openid=55107C3B8501CD7CBD90AEE4626E6D17&prepay_id=beaf257883b098007ca821e1c59f7f7a&session_key=VUNQZ0hRYURxNlZZbmNOZw==')
  2. var_dump(bin2hex($h));
  4. 签名：
  5. 9a721574bbf7fbfc68f15edd7e9cc355d6a95e2d946ecd4e04b708c4206665b4