文档

# 小游戏支付

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

# 业务流程

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

# 开通小游戏支付

# 上架道具

开发者需要在QQ小程序开发者管理端上架道具

# 预下单

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

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

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

# 请求参数

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

# 返回值

# Object

返回的 JSON 数据包

属性 类型 说明
errcode number 错误码
errmsg string 错误信息
prepayId string 订单号，有效期是 48 小时

errcode 的合法值

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

# POST 数据格式：JSON

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

# 计算签名

  1. 请求方法： POST

  2. 下单url中的path（/api/json/openApiPay/GamePrePay）部分，做标准的url Encoding, 标准请参考《URL Encoding》

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

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
1
  1. 拼接session_key，用户登录时开发者后台可以通过code2session接口获取到
session_key=VUNQZ0hRYURxNlZZbmNOZw==
1
  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==
1
  1. HMAC-SHA256得到的签名结果
$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);
var_dump(bin2hex($h));

签名：
38181bd0acf24eda203655a3be9f2e42b62d4fcf1c1de61a98b0573d13531449
1
2
3
4
5

# 通知发放道具

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

# 请求参数

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

# 回调地址

这里的回调地址是示例，以开发者在管理端配置的为准

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

# POST 数据格式：JSON

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

# 签名

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

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

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

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

# 返回值

回调接口需要返回一个json

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

# 查询支付状态

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

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

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

# 请求参数

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

# 返回值

# Object

返回的 JSON 数据包

属性 类型 说明
errcode number 错误码
errmsg string 错误信息
pay_state number 支付状态: 0： 未支付, 1: 已支付
pay_time number 支付时间戳(单位秒)
app_remark string

errcode 的合法值

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

# POST 数据格式：JSON

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

# 计算签名

  1. 请求方法： POST

  2. 查询url中的path（/api/json/openApiPay/CheckGamePay）部分，做标准的url Encoding, 标准请参考《URL Encoding》

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

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

签名：
66494923186839a01bd85d528260daabeb507a6a28e5934335dd4ef9cca894f0
1
2
3
4
5

# 查询余额

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

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

# 请求参数

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

# 返回值

# Object

返回的 JSON 数据包

属性 类型 说明
errcode number 错误码
errmsg string 错误信息
remainder number 金币余额

errcode 的合法值

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

# POST 数据格式：JSON

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

# 计算签名

  1. 请求方法： POST

  2. 下单url中的path（/api/json/openApiPay/GetBalance）部分，做标准的url Encoding, 标准请参考《URL Encoding》

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

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

签名：
9a721574bbf7fbfc68f15edd7e9cc355d6a95e2d946ecd4e04b708c4206665b4
1
2
3
4
5

← 接口调用凭证 →