腾讯移动支付插件Midas白皮书

目录


1. 支付后台接口API

1.1 API

1.1.1 查询余额接口

(1)URL地址
【现网】https:// ysdk.qq.com/mpay/get_balance_m
【沙箱】https://ysdktest.qq.com/mpay/get_balance_m

(2)功能说明
获取用户游戏币余额
注:由于渠道存在扣费延时的问题,所以在充值完成后调用该接口是建议在2分钟之内间隔15秒多次调用,直到查到当前充值已到账(是否到账可以通过接口返回的save_amt对应的值是否发送变化来判断)
Cookie里面需要包含的参数:
session_id 用户账户类型,(手Q)session_id ="openid";(微信)session_id = "hy_gameid"; (游客) session_id = "hy_gameid"; (h5游戏) session_id ="openid"
session_type session类型,(手Q)session_type = "kp_actoken";(微信)session_type = "wc_actoken" ;(游客) session_type = "st_dummy"; (h5游戏) session_type ="openkey"
org_loc 需要填写: /mpay/get_balance_m
appip (可选)来源的第三方应用的服务IP
注意:cookie里面参数的值,需要进行urlencode

请求参数
openid:从手Q登录态或微信登录态中获取的openid的值
openkey:手Q登陆时传手Q登陆回调里获取的paytoken值,微信登陆时传微信登陆回调里获取的传access_token值。
appid:offerid,offerid即支付结算页面里的应用id,用于支付接口。
ts:UNIX时间戳(从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数)。
sig:请求串的签名(参考YSDK支付接口签名说明)。
pf:平台来源,登录获取的pf值
pfkey:登录获取的pfkey值
zoneid:账户分区ID_角色ID。每个应用都有一个分区ID为1的默认分区,分区可以在cpay.qq.com/mpay上自助配置。如果应用选择支持角色,则角色ID接在分区ID号后用"_"连接,角色ID需要进行urlencode。
userip:(可选)用户的外网IP accounttype:(可选)帐户类型ID。基础货币(common);安全货币(security);不填,默认common
format:(可选)json、jsonp_$func。默认json。如果jsonp,前缀为:$func
例如:format=jsonp_sample_pay,返回格式前缀为:sample_pay()

(3)返回参数
ret:返回码。0:成功;1001:参数错误;1018:登陆校验失败。
其它:失败
balance:游戏币个数(包含了赠送游戏币)
gen_balance: 赠送游戏币个数
first_save: 是否满足首次充值,1:满足,0:不满足。
save_amt: 累计充值金额的游戏币数量
gen_expire:该字段已作废
tss_list: 月卡信息字段,如果没有月卡该字段值为空
innerproductid 用户开通的订阅物品id(注:该参数为计费分配的订阅物品的servicecode)
begintime 用户订阅的开始时间
endtime 用户订阅的结束时间
paychan 用户订阅该物品id最后一次的支付渠道
paysubchan 用户订阅该物品id最后一次的支付子渠道id
autopaychan 预留扩展字段,目前没有使用
autopaysubchan 预留扩展字段,目前没有使用
grandtotal_opendays 用户订阅累计开通天数
grandtotal_presentdays 用户订阅累计赠送天数
first_buy_time 首充开通时间
extend 预留扩展字段,目前没有使用

(4)返回示例
正确返回示例

Content-type: text/html; charset=utf-8
 {
 "ret":0,
 "balance":3989,
"gen_balance":256,
"first_save":0,
 "save_amt":4000,
 "gen_expire":0,
 "tss_list":[{
	"innerproductid" : "1450000594-1001",
	"begintime" : "2014-08-21 18:15:24",
	"endtime" : "2014-09-20 18:15:24",
	"paychan" : "iap",
	"paysubchan" : 1,
	"autopaychan" : "",
	"autopaysubchan" : 0,
	"grandtotal_opendays" : 32737,
	"grandtotal_presentdays" : 1,
	"first_buy_time" : "4457674-07-08 01:37",
	"extend" : ""
	}
	]
 }
 

错误返回示例

Content-type: text/html; charset=utf-8
{"ret":1018,"msg":"请先登录"}
 

(5)签名示例
第一步,按OpenAPI V3.0的签名生成说明,构造源串。得到的源串为:
GET&%2Fv3%2Fr%2Fmpay%2Fget_balance_m&appid%3D15499%26format%3Djson%26openid%3D00000000000000000000000014BDF 6E4%26openkey%3DAB43BF3DC5C3C79D358CC5318E41CF59%26pf%3Dmyapp_m_qq-00000000-android-00000000-ysdk%26pfkey %3DCA641BC173479B8C0B35BC84873B3DB9%26ts%3D1340880299%26userip%3D112.90.139.30%26zoneid%3D1

第二步,按OpenAPI V3.0的签名生成说明,构造密钥。得到的密钥为:
56abfbcd12fe46f5ad85ad9f12345678&

第三步,根据HMAC-SHA1加密算法将源串以及密钥进行加密,然后对加密后的字符串经过Base64编码后,得到的Sig的值为:
SqI7fyvtnWBYMfERV8hZc9YQXp0=

请求串:
http://IP/mpay/get_balance_m?appid=15499&format=json&openid=00000000000000000000000014BDF6E4&openkey=AB43BF3DC5 C3C79D358CC5318E41CF59&pf=myapp_m_qq-00000000-android-00000000-ysdk&pfkey=CA641BC173479B8C0B35BC84873B3DB9&ts= 1340880299&userip=112.90.139.30&zoneid=1&sig=SqI7fyvtnWBYMfERV8hZc9YQXp0%3D

1.1.2 扣除游戏币接口

(1)URL地址
【现网】https://ysdk.qq.com/mpay/pay_m
【沙箱】https://ysdktest.qq.com/mpay/pay_m

(2)功能说明
扣除用户游戏币。如发货失败,必须调用退款接口(cancel_pay_m)

(3)参数说明
Cookie里面需要包含的参数
session_id 用户账户类型,(手Q)session_id ="openid";(微信)session_id = "hy_gameid"; (游客) session_id = "hy_gameid"; (h5游戏) session_id ="openid"
session_type session类型,(手Q)session_type = "kp_actoken";(微信)session_type = "wc_actoken" ;(游客) session_type = "st_dummy"; (h5游戏) session_type ="openkey"
org_loc 需要填写: /mpay/pay_m
appip (可选)来源的第三方应用的服务IP
注意:cookie里面参数的值,需要进行urlencode

请求参数 openid:从手Q登录态或微信登录态中获取的openid的值
openkey:手Q登陆时传手Q登陆回调里获取的paytoken值,微信登陆时传微信登陆回调里获取的传access_token值。
appid:offerid,offerid即支付结算页面里的应用id,用于支付接口。
ts:UNIX时间戳(从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数)。
sig:请求串的签名(参考YSDK支付接口签名说明)。
pf:登录获取的pf值
pfkey:登录获取的pfkey值
zoneid:账户分区ID_角色ID。每个应用都有一个分区ID为1的默认分区,分区可以在cpay.qq.com/mpay上自助配置。如果应用选择支持角色,则角色ID接在分区ID号后用"_"连接,角色ID需要进行urlencode。
amt:扣游戏币数量,atn不能为0。
billno:订单号,业务自定义,业务需要确保全局的唯一性;相同的订单号不会重复扣款。长度不超过63字节,数字和字符不限,不能包含特殊字符如&= | % ^ + 等即可
userip:(可选)用户的外网IP
payitem:(可选)道具名称。
accounttype:(可选)帐户类型ID, 基础货币(common) 安全货币(security), 不填默认common
format:(可选)json、jsonp_$func。默认json。如果jsonp,前缀为:$func 例如:format=jsonp_sample_pay,返回格式前缀为:sample_pay()
appremark: (可选)备注。会写到账户流水。

(4)返回参数
示例:
ret:返回码
0:成功;
1004:余额不足。
1018:登陆校验失败。
其它:失败
billno:预扣流水号
balance:预扣后的余额

(5)返回示例 正确返回示例:
Content-type: text/html; charset=utf-8
{"ret" : 0,"billno" : "20102"}
错误返回示例
Content-type: text/html; charset=utf-8
{"ret":1018,"msg":"请先登录"}

1.1.3 取消支付接口

(1)URL地址
【现网】https://ysdk.qq.com/mpay/cancel_pay_m
【沙箱】https://ysdktest.qq.com/mpay/cancel_pay_m

(2)功能说明
退款。扣费成功,发货失败后,必须调用本接口。如果不调默认将进行扣费确认。

(3)请求参数
Cookie里面需要包含的参数:
session_id 用户账户类型,(手Q)session_id ="openid";(微信)session_id = "hy_gameid"; (游客) session_id = "hy_gameid"; (h5游戏) session_id ="openid"
session_type session类型,(手Q)session_type = "kp_actoken";(微信)session_type = "wc_actoken" ;(游客) session_type = "st_dummy"; (h5游戏) session_type ="openkey"

org_loc 需要填写: /mpay/cancel_pay_m
appip (可选)来源的第三方应用的服务IP
注意:cookie里面参数的值,需要进行urlencode

请求参数
openid:从手Q登录态或微信登录态中获取的openid的值
openkey:手Q登陆时传手Q登陆回调里获取的paytoken值,微信登陆时传微信登陆回调里获取的传access_token值。
appid:offerid,offerid即支付结算页面里的应用id,用于支付接口。
ts:UNIX时间戳(从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数)。
sig:请求串的签名(参考YSDK支付接口签名说明)。
pf:登录获取的pf值
pfkey: 登录获取的pfkey值
zoneid:账户分区ID_角色ID。每个应用都有一个分区ID为1的默认分区,分区可以在cpay.qq.com/mpay上自助配置。如果应用选择支持角色,则角色ID接在分区ID号后用"_"连接,角色ID需要进行urlencode。
amt:扣游戏币数量。
billno:预扣流水号。
ts:UNIX时间戳(从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数)。
userip:(可选)用户的外网IP
accounttype:可选)帐户类型ID, 基础货币(common) 安全货币(security), 不填默认common
format:可选)json、jsonp_$func。默认json。如果jsonp,前缀为:$func
例如:format=jsonp_sample_pay,返回格式前缀为:sample_pay()

(4)返回参数
ret:返回码
返回码说明
0:成功;
1018:登陆校验失败。
其它:失败

(5)返回示例
JSON示例:
Content-type: text/html; charset=utf-8
{"ret":0 }
错误返回示例
Content-type: text/html; charset=utf-8
{"ret":1018,"msg":"请先登录"}

1.1.4 直接赠送接口

(1)URL地址
【现网】https://ysdk.qq.com/mpay/present_m
【沙箱】https://ysdktest.qq.com/mpay/present_m

(2)功能说明
直接赠接口,可以用于赠送游戏币。赠送的游戏币不参与结算分成。

(3)请求参数
Cookie里面需要包含的参数
session_id 用户账户类型,(手Q)session_id ="openid";(微信)session_id = "hy_gameid"; (游客) session_id = "hy_gameid"; (h5游戏) session_id ="openid"
session_type session类型,(手Q)session_type = "kp_actoken";(微信)session_type = "wc_actoken" ;(游客) session_type = "st_dummy"; (h5游戏) session_type ="openkey"
org_loc 需要填写: /mpay/present_m
appip (可选)来源的第三方应用的服务IP
注意:cookie里面参数的值,需要进行urlencode

请求参数
openid:从手Q登录态或微信登录态中获取的openid的值
openkey:手Q登陆时传手Q登陆回调里获取的paytoken值,微信登陆时传微信登陆回调里获取的传access_token值。
appid:offerid,offerid即支付结算页面里的应用id,用于支付接口。
ts:UNIX时间戳(从格林威治时间1970年01月01日00时00分00秒起至现在的总秒数)。
sig:请求串的签名(参考YSDK支付接口签名说明)。
pf:登录获取的pf值
zoneid:账户分区ID_角色ID。每个应用都有一个分区ID为1的默认分区,分区可以在cpay.qq.com/mpay上自助配置。如果应用选择支持角色,则角色ID接在分区ID号后用"_"连接,角色ID需要进行urlencode。
pfkey:登录获取的pfkey值
presenttimes:表示要赠送游戏币的个数,大于零的整数。
billno:订单号,业务自定义,业务需要确保全局的唯一性;相同的订单号不会重复扣款。长度不超过63字节,数字和字符不限,不能包含特殊字符如&= | % ^ + 等即可
userip:(可选)用户的外网IP
format:(可选)json、jsonp_$func。默认json。如果jsonp,前缀为:$func
例如:format=jsonp_sample_pay,返回格式前缀为:sample_pay()

(4)返回参数
ret:返回码
0:成功
非0:失败
1018:登陆校验失败。
2.1.3.5.返回示例
正确返回示例:
Content-type: text/html; charset=utf-8
{"ret":0}
错误返回示例
Content-type: text/html; charset=utf-8
{"ret":1018,"msg":"请先登录"}

1.1.5 应用消耗游戏币买道具一般流程

yidongzhifuchajianMidas_01.png

1.2 OpenAPI V3.0 签名校验工具

http://open.qq.com/tools

2. FAQ

2.1 Q:android版本要求?

A:该支付SDK支持android2.1及以上版本

2.2 Q:SDK支付完成后,能否通知应用充值数量及是否充值成功?

A:Q点Q币、Q卡是实时到账,财付通渠道、快捷、手机充值卡为非实时到账,所以SDK也无法实时确定发货成功。而且SDK回调通知应用购买数量及是否成功存在安全隐患,因为这个是本地调用。应用可以通过调用后台API向服务器发起请求查询用户余额。

2.3 Q:调用SDK时pf和pfkey如何确定?

A:pf为应用侧构造传递给SDK。pf的格式为平台标识信息:平台-渠道-系统运行平台-业务自定义。渠道表示应用发布的渠道:如应用宝、豌豆荚等,用数字表示(具体如何表示业务侧定义,SDK侧不关心)。系统运行平目前支持android、ios
例如:
手Q:openmobile_android-2001-android-xxxx
pfKey为应用所在平台下方,SDK侧不关心,只做透传处理。对应自研应用后台对pfKey不做校验,应用可以传递为pfKey = “pfKey”。对于非自研应用后台强校验,应用需要从开放平台侧获取传递给SDK。

2.4 Q:什么是基础货币和安全货币?

A:基础货币:普通支付应用场景使用,充值基础货币后,用于普通购买行为。满足常用的支付需求。
安全货币:如果应用有特殊要求,例如:要求寄售道具场景(玩家之间的道具买卖)只能用特殊的货币进行交易,那么可以使用安全货币,区别于基础货币,安全货币也用于购买道具。(可选货币)

2.5 Q:支付时为什么会登录态过期?

A:支付的登录态时效性要求比较高,因此需要应用拉起支付时,先更新下登录态,这样能保证支付过程中尽可能出现少的登录态失效。如果用户在支付页面停留过长时间,支付时提示登录态过期,支付会回调应用,应用应该再重新获取用户的登录态再进行支付。
如果应用在接入联调时一直出现登录态过期,支付的log中出现错误码1018,那就说明传递的参数是有误的,请确认sessionId,sessionType,userId和userKey的正确性,具体请参看调用接口时的参数说明。如果还提示1018错误,请确认应用在微信,手Q平台上申请的ID和Key 和支付接入时配置的一致。

2.6 Q:道具直购和购买游戏币有什么区别

A:购买游戏币需要对货币进行托管,而道具则不需要托管。购买游戏币由腾讯支付服务端负责发货。购买道具需要应用侧提供发货回调接口,当腾讯服务端扣款后回调应用的发货接口。

3. 附录

3.1 SDK弹框错误错误码

1001-xxxx-xxxx 表示参数错误
1003-50000X-xxxx 表示应用侧发货失败

以上信息是否解决您的问题?

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部