回调道具交换URL的协议说明

特别声明
1. 本文档基于V3版OpenAPI协议。
2. 本接口仅适用于在支付接入中提交寄售接入申请并审核通过的应用。使用前请确保你的应用具有该OpenAPI的访问权限。

目录

1 什么是道具交换URL?

道具交换URL是提交申请时填写的“发货URL”(详见:支付接入申请说明#3. 支付接入申请时需填写的基本资料),由应用指定。
开发者请按照下列协议进行发货URL的开发。
道具交换URL用于提供给腾讯后台回调。在寄售系统中,用户A购买用户B的道具付费成功后,腾讯后台将回调该URL将道具从用户B转到用户A下。

本接口在以下场景使用:道具寄售模式-道具寄售

属于以下流程中的第7步:
exchange_goods.png

2 协议参数

请开发者特别关注:
平台后续可能对协议进行扩展,因此请不要将参与签名的参数写死。
计算签名时,请以每笔交易接收到的参数为准,接收到的所有参数除sig以外都要参与签名。

参数名称 是否必须 类型 描述
openid 必须 string 在道具寄售系统中,购买道具的用户openid。

与APP通信的用户key,跳转到应用首页后,URL后会带该参数。由平台直接传给应用,应用原样传给平台即可。
根据APPID以及QQ号码生成,即不同的appid下,同一个QQ号生成的OpenID是不一样的。

appid 必须 string 应用的唯一ID。可以通过appid查找APP基本信息。
ts 必须 string linux时间戳。

注意开发者的机器时间与腾讯计费开放平台的时间相差不能超过15分钟。

payitem 必须 string 物品购买信息。

(1)接收标准格式为ID*price*num,回传时ID为必传项。批量购买套餐物品则用“;”分隔,字符串中不能包含"|"特殊字符。
(2)ID表示物品ID,price表示单价(以Q点为单位,单价最少不能少于2Q点,1Q币=10Q点。单价的制定需遵循道具定价规范),num表示购买数量。
示例:
批量购买套餐,套餐中包含物品1和物品2。物品1的ID为G001,该物品的单价为10Q点,购买数量为1;物品2的ID为G008,该物品的单价为8Q点,购买数量为2,则payitem为:G001*10*1;G008*8*2 。

token 必须 string 应用调用v3/pay/exchange_goods接口成功返回的交易token。

注意,交易token的有效期为15分钟,必须在获取到token后的15分钟内传递该token,否则将会返回token不存在的错误。

billno string 支付流水号(64个字符长度。该字段和openid合起来是唯一的)。
version 必须 string 协议版本号,由于基于V3版OpenAPI,这里一定返回“v3”。
zoneid 必须 string 支付营销分区配置说明页面,配置的分区ID即为这里的“zoneid”。

如果应用不分区,则为0。
回调发货的时候,根据这里填写的zoneid实现分区发货。
注:2013年后接入的寄售应用,此参数将作为分区发货的重要参数,如果因为参数传错或为空造成的收入损失,由开发商自行承担。

providetype 必须 string 发货类型,这里请传入3。

0表示道具购买,1表示营销活动中的道具赠送,2表示交叉营销任务集市中的奖励发放,3表示道具寄售系统中的道具转移。

amt 必须 string Q点/Q币消耗金额或财付通游戏子账户的扣款金额。道具寄售目前暂不支持Q点/Q币/财付通游戏子账户,因此该参数的值为0。
seller_openid 必须 string 道具寄售系统中,售卖道具的用户的openid。
fee 必须 string 应用扣除的佣金,包括扣除公共游戏币账户和分区游戏币账户中的金额。

佣金:用户在应用中售卖道具获得游戏币,需要付给应用一定的游戏币作为佣金。

fee_acct 必须 string 佣金中扣掉Q币Q点的金额,道具寄售目前暂不支持Q点/Q币或财付通子账户支付,因此该参数为0。
fee_pubcoins 必须 string 佣金中扣掉公共游戏币账户金额,包括充值得到的游戏币和赠送得到的游戏币。

其中赠送得到的游戏币不参与结算,如无公共游戏币账户则为0。

fee_pubcoins_save 必须 string 佣金中扣掉公共游戏币账户中通过充值得到的游戏币金额,该金额将参与结算。

如无公共游戏币账户则为0。

fee_coins 必须 string 佣金中扣掉分区游戏币账户金额,包括充值得到的游戏币和赠送得到的游戏币。

其中赠送得到的游戏币不参与结算,如无分区游戏币账户则为0。

fee_coins_save 必须 string 佣金中扣掉分区游戏币账户中通过充值得到的游戏币金额,该金额将参与结算。

如无分区游戏币账户则为0。

uni_appamt 必须 string 购买的道具的价格。

注意,这里以0.1Q点为单位。即如果总金额为18Q点,则这里显示的数字是180。请开发者关注,特别是对账的时候注意单位的转换。

cee_extend 必须 string 部署在CEE_V2的应用,必须传入该参数,用于将请求转发到对应的应用下的支付相关Web服务上进行处理。该参数不参与签名计算。

详见:CEE_V2访问云支付

sig 必须 string 请求串的签名,由需要签名的参数生成。

(1)签名方法请见文档:腾讯开放平台第三方应用签名参数sig的说明
(2)按照上述文档进行签名生成时,需注意回调协议里多加了一个步骤:
在构造源串的第3步“将排序后的参数(key=value)用&拼接起来,并进行URL编码”之前,需对value先进行一次编码 (编码规则为:除了 0~9 a~z A~Z !*() 之外其他字符按其ASCII码的十六进制加%进行表示,例如“-”编码为“%2D”)。
(3)以每笔交易接收到的参数为准,接收到的所有参数除sig以外都要参与签名。为方便平台后续对协议进行扩展,请不要将参与签名的参数写死。
(4)所有参数都是string型,进行签名时必须使用原始接收到的string型值。 开发商出于本地记账等目的,对接收到的某些参数值先转为数值型再转为string型,导致字符串部分被截断,从而导致签名出错。如果要进行本地记账等逻辑,建议用另外的变量来保存转换后的数值。

3 协议返回包

应用的返回包应该包含如下参数:

ret: 返回码。

msg: 道具交换操作的结果,成功为“OK”,失败则表明错误原因(必须使用utf8编码)。

腾讯设置的调用第三方发货超时是2秒钟,请第三方注意超时时间设置不要超过2秒,否则腾讯后台将返回“系统繁忙”的错误消息。

4 协议错误码

应用的错误码应该从0开始,按照整数递增的方式进行定义,建议应用按照如下描述定义错误码:

0: 成功

1: 系统繁忙

2: token已过期

3: token不存在

4: 请求参数错误:(这里填写错误的具体参数)

5 请求示例

回调发货请求的签名生成较为复杂,许多应用在此出错,因此下面演示了sig签名的生成细节。开发者可以下面的示例来验证sig的详细过程,但不能直接复制。

第一步: 应用接收到腾讯支付后台发送过来的请求
该请求通过后台发送,因此所有参数都未进行URL编码。但是该请求中所带的sig却进行了URL编码(这一点请开发者关注,在回调协议中这里比较特殊)。
请求示例如下:
http://ip/cgi-bin/demo_provide.cgi?amt=0&appid=15499&billno=-APPDJ10153-20120809-1150429539&fee=10&
fee_acct=0&fee_coins=10&fee_coins_save=10&fee_pubcoins=0&fee_pubcoins_save=0&openid=0000000000000000000
000000E1E0000&payitem=50005*2*10&providetype=3&seller_openid=000000000000000000000000008FA509&
token=2854C0C5BEC0AC942C020846C0D0B33129885&ts=1344484244&uni_appamt=200&version=v3&zoneid=1&
sig=ZCKQN%2F0%2FBRNxzkrmK6GiwL1hyG8%3D

特别提示:
请求中的红色部分为应用指定的发货URL,是提交支付接入申请时填写的“发货URL”(详见:支付接入申请说明#3. 支付接入申请时需填写的基本资料)。

第二步: 应用对该请求进行解析,根据得到的请求源参数来计算sig
对上面的请求进行解析,得到源参数如下:

method:GET
url_path: /cgi-bin/demo_provide.cgi
假设appkey为:56abfbcd12fe46f5ad85ad9f2faf36d7


请求源参数以及对应的值为:(注意:请以接收到的参数为准,除sig外的所有参数都需要参与签名) 
amt:0
appid: 15499
billno: -APPDJ10153-20120809-1150429539
fee:10
fee_acct:10
fee_coins:10
fee_coins_save:10
fee_pubcoins:0
fee_pubcoins_save:0
openid: 0000000000000000000000000E1E0000
payitem: 50005*2*10
providetype: 3
selleropenid:000000000000000000000000008FA509
token: 2854C0C5BEC0AC942C020846C0D0B33129885
ts: 1344484244
uni_appamt:200
version: v3
zoneid: 1


在回调发货协议中,在进行签名生成时,回调协议里多加了一个步骤:
在构造源串第3步之前(sig生成通用步骤说明详见这里),需对value先按照如下编码规则进行编码(注意这里不是urlencode):
除了 0~9 a~z A~Z !*() 之外其他字符按其ASCII码的十六进制加%进行表示,例如“-”编码为“%2D”。
payitem中,单价如果有小数点“.”,请编码为“%2E”。


编码后的参数为:
amt:0
appid: 15499
billno: %252DAPPDJ10153%252D20120809%252D1150429539
fee:10
fee_acct:10
fee_coins:10
fee_pubcoins:0
fee_pubcoins_save:0
openid: 0000000000000000000000000E1E0000
payitem: 50005*2*10
providetype: 3
selleropenid:000000000000000000000000008FA509
token: 2854C0C5BEC0AC942C020846C0D0B33129885
ts: 1344484244
uni_appamt:200
version: v3
zoneid: 1


执行构造源串的第3步:“将排序后的参数(key=value)用&拼接起来,并进行URL编码”(sig生成通用步骤说明详见这里)。


则源串为:GET&%2Fcgi-bin%2Fdemo_provide.cgi&amt%3D0%26appid%3D15499%26billno%3D%252DAPPDJ10153%252D20120809
%252D1150429539%26fee%3D10%26fee_acct%3D0%26fee_coins%3D10%26fee_coins_save%3D10%26fee_pubcoins%3D0%26
fee_pubcoins_save%3D0%26openid%3D0000000000000000000000000E1E0000%26payitem%3D50005%2A2%2A10%26
providetype%3D3%26seller_openid%3D000000000000000000000000008FA509%26token%3D2854C0C5BEC0AC942C0208
46C0D0B33129885%26ts%3D1344484244%26uni_appamt%3D200%26version%3Dv3%26zoneid%3D1


密钥为:56abfbcd12fe46f5ad85ad9f2faf36d7&


生成的签名为:ZCKQN/0/BRNxzkrmK6GiwL1hyG8=


第三步: 应用将自己生成的sig与腾讯支付后台发送的请求中的sig进行比对
注意: 应用接收到的腾讯支付平台发送过来的请求后,请先对请求中的sig值做一次URL解码;
然后再将解码后的sig值与应用自己生成的sig值进行比对。
在PHP中,通过$_GET['sig']获取sig值,PHP语言本身对sig值进行了URL解码,不需要再次解码。

如果sig值一致,表示该请求合法,应用可以处理该请求并将结果返回给腾讯支付后台。

6 返回示例

正确返回示例:

Content-type: text/html; charset=utf-8
{
"ret":0,
"msg":"OK"
}

错误返回示例:

Content-type: text/html; charset=utf-8
{
"ret":4,
"msg":"请求参数错误:(sig)"
}


相关文档

上一步:fusion2.dialog.buy
下一步:v3/pay/confirm_delivery

其他相关文档:支付接入#支付接入文档索引 | 支付测试环境说明 | 支付错误码说明 | 支付功能开发相关FAQ

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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部