购买道具扣款成功回调应用发货

特别声明：
1. 本文档基于V3版OpenAPI协议。
2. Hosting应用发货URL只需HTTP协议即可。

1. 什么是发货URL？

发货URL即提交支付接入申请时填写的“发货URL”（详见：支付接入申请说明#3. 支付接入申请时需填写的基本资料）。
本接口在游戏选择直购模式时使用。游戏币模式不需要配置回调发货路径。
开发者请按照下列协议进行发货URL的开发。
发货URL用于提供给腾讯后台回调。用户付费成功后，腾讯后台将回调该URL给用户发货，将道具发给用户。

本接口在以下场景使用：
（1）Q点直购模式

属于以下流程中的第7步：

2. 协议参数

请开发者特别关注：
平台后续可能对协议进行扩展，产生随机参数，因此请不要将参与签名的参数写死。
计算签名时，请以每笔交易接收到的参数为准，接收到的所有参数除sig和cee_extend以外都要参与签名。
注意：由于移动端应用回调应用发货接口时会新增appmeta 、clientver参数，该参数也参与sig签名计算。

参数名称	类型	描述
openid	string	从手Q登录态中获取的openid的值。由平台直接传给应用，应用原样传给平台即可。根据APPID以及QQ号码生成，即不同的appid下，同一个QQ号生成的OpenID是不一样的。
appid	string	应用的唯一ID。可以通过appid查找APP基本信息。
ts	string	linux时间戳。秒为单位注意开发者的机器时间与腾讯计费开放平台的时间相差不能超过15分钟。
payitem	string	物品信息。（1）接收标准格式为IDpricenum，回传时ID为必传项。批量购买套餐物品则用“;”分隔，字符串中不能包含"\|"特殊字符。（2）ID表示物品ID，price表示单价（以Q点为单位，单价最少不能少于1Q点，1Q币=10Q点。单价的制定需遵循道具定价规范），num表示最终的购买数量。示例：批量购买套餐，套餐中包含物品1和物品2。物品1的ID为G001，该物品的单价为10Q点，购买数量为1；物品2的ID为G008，该物品的单价为8Q点，购买数量为2，则payitem为：G001101;G00882 。
token	string	应用调用mpay/buy_goods_m接口成功返回的交易token。注意，交易token的有效期为15分钟，必须在获取到token后的15分钟内传递该token，否则将会返回token不存在的错误。
billno	string	支付流水号（64个字符长度。该字段和openid合起来是唯一的）。
version	string	协议版本号，由于基于V3版OpenAPI，这里一定返回“v3”。
zoneid	string	在分区配置里的分区ID即为这里的“zoneid”。如果应用不分区，移动端的zoneid则默认为1。回调发货的时候，根据这里填写的zoneid实现分区发货。注：2013年后接入的寄售应用，此参数将作为分区发货的重要参数，如果因为参数传错或为空造成的收入损失，由开发商自行承担。
providetype	string	发货类型。 5表示移动端道具购买。
amt	string	Q点/Q币消耗金额或财付通游戏子账户的扣款金额。可以为空，若传递空值或不传本参数则表示未使用Q点/Q币/财付通游戏子账户。允许游戏币、Q点、抵扣券三者混合支付，或只有其中某一种进行支付的情况。用户购买道具时，系统会优先扣除用户账户上的游戏币，游戏币余额不足时，使用Q点支付，Q点不足时使用Q币/财付通游戏子账户。这里的amt的值将纳入结算，参与分成。注意，这里以0.1Q点为单位。即如果总金额为18Q点，则这里显示的数字是180。请开发者关注，特别是对账的时候注意单位的转换。
payamt_coins	string	扣取的游戏币总数，单位为Q点。可以为空，若传递空值或不传本参数则表示未使用游戏币。允许游戏币、Q点、抵扣券三者混合支付，或只有其中某一种进行支付的情况。用户购买道具时，系统会优先扣除用户账户上的游戏币，游戏币余额不足时，使用Q点支付，Q点不足时使用Q币/财付通游戏子账户。游戏币由平台赠送或由好友打赏，平台赠送的游戏币不纳入结算，即不参与分成；好友打赏的游戏币按消耗量参与结算（详见：货币体系与支付场景）。
pubacct_payamt_coins	string	扣取的抵用券总金额，单位为Q点。可以为空，若传递空值或不传本参数则表示未使用抵扣券。允许游戏币、Q点、抵扣券三者混合支付，或只有其中某一种进行支付的情况。用户购买道具时，可以选择使用抵扣券进行一部分的抵扣，剩余部分使用游戏币/Q点。平台默认所有上线支付的应用均支持抵扣券。自2012年7月1日起，金券银券消耗将和Q点消耗一起纳入收益计算（详见：货币体系与支付场景）。
appmeta	string	在buy_goods_m的设定的自定义参数app_metadata，会透传到appmeta里，格式为自定义字段支付方式平台渠道，比如customkeyqdqbqq。应用侧这边根据此格式自行提取自定义部分的值。注意如果有比如“-”、“_”等特殊符号，在计算sig时替换为“%2D”、“%5F”等。
clientver	string	客户端渠道。Android平台的应用回调时返回clientver=android，IOS平台的应用返回时clientver=iap。
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秒，否则腾讯后台将返回“系统繁忙”的错误消息。
返回建议：
1.在发货接口中记录被调用的log，用于查看是否发货回调接口能够被腾讯支付服务器回调，发起一笔支付请求，查看发货回调接口是否有被调用。
2.联调回调发货接口时先在接口上固定返回发货成功的标准json字符串{"ret":0,"msg":"OK"}，测试一次支付，查看支付服务器是否能正常接收到回调发货接口返回的标准json内容。
注意：返回的内容中不能有空格、tab等字符、不能有其它多余的内容。
3.以上两步都能顺利通过，说明回调接口能正常被支付服务器调用，然后再在回调接口中加入游戏发货的业务逻辑。

4. 协议错误码

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

0: 成功

1: 系统繁忙

2: token已过期

3: token不存在

4: 请求参数错误：（这里填写错误的具体参数）

5. 请求示例

sig签名SDK下载 wiki下载地址： http://wiki.open.qq.com/wiki/SDK%E4%B8%8B%E8%BD%BD#OpenAPI_V3.0_SDK.E4.B8.8B.E8.BD.BD

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

第一步：应用接收到腾讯支付后台发送过来的请求。
该请求通过后台发送，因此所有参数都未进行URL编码。但是该请求中所带的sig却进行了URL编码，其中“=”编码为%3D，如果有“+”编码为“%2B”
（这一点请开发者关注，在回调协议中这里比较特殊，而且字母是大写）。
请求示例如下：
http://ip/pay/mt.php?amt=320&appid=1101255891&appmeta=customkey*qdqb*qq&billno=-APPDJSX18246-20140401-
1206311492&clientver=android&openid=F11669C63D76BAB0BC2F6CC869B19E53&payamt_coins=0
&payitem=G1*20*2&providetype=5&pubacct_payamt_coins=&token=5056117C0597793C38C4F1D29F884C5E25887
&ts=1396325191&version=v3&zoneid=1&sig=ai1eD5CA16n5pWBx9abjZguMR5Y%3D

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

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

method:GET
url_path: /pay/mt.php
假设appkey为： Lf6AtMEB1QlE8BYS

请求源参数以及对应的值为：（注意：请以接收到的参数为准，除sig外的所有参数都需要参与签名）

amt : 320
appid : 1101255891
appmeta : customkey*qdqb*qq
billno : -APPDJSX18246-20140401-1206311492
clientver : android
openid : F11669C63D76BAB0BC2F6CC869B19E53
payamt_coins : 0
payitem : G1*20*2
providetype : 5
pubacct_payamt_coins :
token : 5056117C0597793C38C4F1D29F884C5E25887
ts : 1396325191
version : v3
zoneid : 1

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

编码后的参数为：

amt : 320
appid : 1101255891
appmeta : customkey*qdqb*qq
billno : %2DAPPDJSX18246%2D20140401%2D1206311492
clientver : android
openid : F11669C63D76BAB0BC2F6CC869B19E53
payamt_coins : 0
payitem : G1*20*2
providetype : 5
pubacct_payamt_coins :
token : 5056117C0597793C38C4F1D29F884C5E25887
ts : 1396325191
version : v3
zoneid : 1

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

则源串为GET&%2Fpay%2Fmt.php&amt%3D320%26appid%3D1101255891%26appmeta%3Dcustomkey%2Aqdqb%2Aqq
%26billno%3D%252DAPPDJSX18246%252D20140401%252D1206311492
%26clientver%3Dandroid%26openid%3DF11669C63D76BAB0BC2F6CC869B19E53%26payamt_coins%3D0
%26payitem%3DG1%2A20%2A2%26providetype%3D5%26
pubacct_payamt_coins%3D%26token%3D5056117C0597793C38C4F1D29F884C5E25887%26ts%3D1396325191%26version%3Dv3%26zoneid%3D1

密钥为：Lf6AtMEB1QlE8BYS&

生成的签名为： ai1eD5CA16n5pWBx9abjZguMR5Y=

编码后的签名为: ai1eD5CA16n5pWBx9abjZguMR5Y%3D (注意如果有“+”编码为“%2B”)

第三步：应用将自己生成的sig与腾讯支付后台发送的请求中的sig进行比对。
注意：应用接收到的腾讯支付平台发送过来的请求后，请先对请求中的sig值做一次URL解码；
然后再将解码后的sig值与应用自己生成的sig值进行比对。
在PHP中，通过$_GET['sig']获取sig值，PHP语言本身对sig值进行了URL解码，不需要再次解码。
如果sig值一致，表示该请求合法，应用可以处理该请求并将结果返回给腾讯支付后台。

6. 返回示例

正确返回示例：（必须在2秒内发货并返回此应答。）

{"ret":0,"msg":"OK"}

错误返回示例：

{"ret":4,"msg":"请求参数错误：（sig）"}

资料库