v3/pay/buy_goods

特别声明

1. 本OpenAPI仅开放给已提交接入支付申请并通过的应用。使用前请确保你的应用具有该OpenAPI的访问权限。
2. 本接口需要使用HTTPS协议访问。

目录

What's New?

2013年2月1日,增加输入参数“max_num”,用来限制用户可购买道具数量的最大值,仅当应用接入“Q点直购”模式,且参数“appmode”的值为2时,可以输入该参数。
2012年10月26日,增加输入参数“paymode”,标识是否为游戏币快捷支付,仅接入“道具寄售”模式且具有功能性支付场景的应用可使用该支付方式。

2012年9月27日,增加输入参数“amttype”,标识支付方式是否为纯游戏币支付。

2012年8月16日起,本接口中的参数“zoneid”在单区单服情况下,由可选改为必传参数。该变化向前兼容,即原来已上线支付的的单区单服应用zoneid可以不传值,系统默认为0。

2012年8月3日起,本接口中的参数“goodsmeta”在发送请求前无需特别进行Base64编码。该变化向前兼容,即原有已经接入的应用如果对“goodsmeta”进行了Base64编码也不会受影响。

1 功能说明

用户点击按钮选择“购买”后,应用调用该接口发送请求,以获取本次交易的token,以及购买物品的url参数。

本接口在以下场景使用:
(1)Q点直购模式
(2)道具寄售模式-直购应用道具
(3)道具寄售模式-游戏币快捷支付

属于以下流程中的第2步:
unipay_4.png

2 接口调用说明

2.1 URL

https://[域名]/v3/pay/buy_goods

正式环境域名或测试环境IP详见:API3.0文档#请求URL说明
注意:本接口需要使用HTTPS协议访问。(沙箱测试环境不区分http、https,现网必须使用https,否则会提示“Client request’s protocol is invalid, should ues https”。)

2.2 格式

json

2.3 HTTPS请求方式

GET, POST

2.4 IP限制

TRUE

2.5 输入参数说明

各个参数请进行URL 编码,编码时请遵守 RFC 1738

(1)公共参数
发送请求时必须传入公共参数,详见公共参数说明

(2)私有参数

参数名称 是否必须 类型 描述
pfkey 必须 string 跳转到应用首页后,URL后会带该参数。由平台直接传给应用,应用原样传给平台即可。

表示平台的信息加密串,根据openid,openkey,pf,appid等生成。
注:有的应用调用本接口时会返回pfkey非法的错误,这种错误可能由以下原因引起:
(1)传入的pf与平台不一致(例如进入的平台是Qzone,但传入的pf是pengyou),导致生成的pfkey错误。
pf值是由平台直接传给应用,应用原样传给平台即可,出现这种错误的原因是开发者自己手动构造的pf值,而不是使用平台传递的值。
(2)传入的openkey不是当前页面返回的openkey。同一个用户如果在不同时间打开多个应用页面,页面返回的openkey是不一样的,这些openkey在各自的页面都可用。当前页面的pfkey应该使用当前页面的openkey来生成。

amt string 表示建议购买的所有物品的总价格,即物品的单价*建议数量(以Q点为单位,1Q币=10Q点)。

如果是批量购买套餐物品,则必须传入amt,amt是所有物品的单价*建议数量之和。

amttype string 表示支付的方式。

coin:仅允许用户使用游戏币支付;
不传:允许用户切换到Q点支付,或者游戏币不足时混合Q点支付。

ts 必须 string linux时间戳,以秒为单位。

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

payitem 必须 string 物品信息。

(1)请使用ID*price*num的格式,批量购买套餐物品则用“;”分隔,字符串中不能包含特殊字符"|"或者回车符。
(2)ID表示物品ID,price表示单价(以Q点为单位,注意1Q点为最小单位,即price必须为整数,单价最少不能少于2Q点(黄钻打折后会舍去小数点后面数值,1Q点打折后单价为0)。1Q币=10Q点,单价的制定需遵循道具定价规范),num表示建议的购买数量。
示例:
批量购买套餐,套餐中包含物品1和物品2。物品1的ID为G001,该物品的单价为10Q点,购买数量为1;物品2的ID为G008,该物品的单价为8Q点,购买数量为2,则payitem为:G001*10*1;G008*8*2 。

appmode string 1表示用户不可以修改物品数量,2表示用户可以选择购买物品的数量。

默认为2;批量购买套餐时,必须等于1。

max_num string 用户可购买的道具数量的最大值。

仅当应用接入“Q点直购”模式,且appmode的值为2时,可以输入该参数。
输入的值需大于参数“payitem”中的num,如果小于num,则自动调整为num的值。

goodsmeta 必须 string 物品信息,格式必须是“name*des”,批量购买套餐时也只能有1个道具名称和1个描述,即给出该套餐的名称和描述。name表示物品的名称,des表示物品的描述信息。用户购买物品的确认支付页面,将显示该物品信息。

长度必须<=256字符,必须使用utf8编码。
目前goodsmeta超过76个字符后不能添加回车字符。

goodsurl 必须 string 物品的图片url,用户购买物品的确认支付页面将显示该物品图片。

长度<=512字符,注意图片规格最大为:116*116 px。

zoneid 必须 string 支付营销分区配置说明页面,配置的分区ID即为这里传入的“zoneid”。

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

manyouid 有时必须 string 如果平台为漫游平台(即公共参数pf值为manyou$siteid),则跳转到应用首页后,URL后会带manyouid。此时调用本支付接口时,必须回传该参数。
present string 用来标识用户是给自己购买物品,或是赠送物品给好友,还是直接向好友索要物品。

0或不传值:表示用户给自己购买物品;
1:表示用户赠送物品给好友,后续进行支付,用于道具赠送场景;
2:表示用户直接向好友索要物品,让好友帮忙支付。
默认为0。

paymode string 标识是否为游戏币快捷支付场景。

1:在接入寄售模式应用中使用游戏币快捷支付功能时,必须传入该参数;
不传:其他支付场景,不需要传入该参数。

cee_extend string 部署在CEE_V2的应用,必须传入该参数,该参数不参与签名计算

详见:CEE_V2访问云支付

2.6 请求示例

本接口的签名生成较为复杂,许多应用在此出错,因此下面演示了sig签名的生成细节。开发者可以下面的示例来验证sig的计算方法,但不能直接复制。

method:GET
url_path:/v3/pay/buy_goods
假设appkey为: 12345f9a47df4d1eaeb3bad9a7e54321

请求参数包括:
amt:4
appid:600
appmode:1
format:json
goodsmeta:道具*测试描述信息!!!
(注: goodsmeta的值必须是是UTF8格式的字符。
2012年8月3日起,无需对字符进行Base64编码,该变化向前兼容,即以前接入的应用如果对字符进行了Base64编码也不受影响)
goodsurl:http://qzonestyle.gtimg.cn/qzonestyle/act/qzone_app_img/app613_613_75.png
openid:0000000000000000000000000E111111
openkey:1111806DC5D1C52150CF405E42222222
payitem:50005*4*1
pf:qzone
pfkey:1B59A5C3D77C7C56D7AFC3E2C823105D
ts:1333674935
zoneid:0

则生成sig时构造的源串为:
GET&%2Fv3%2Fpay%2Fbuy_goods&amt%3D4%26appid%3D600%26appmode%3D1%26format%3Djson%26
goodsmeta%3D%E9%81%93%E5%85%B7%2A%E6%B5%8B%E8%AF%95%E6%8F%8F%E8%BF%B0%E4%BF%A1%E6%
81%AF%EF%BC%81%EF%BC%81%EF%BC%81%26goodsurl%3Dhttp%3A%2F%2Fqzonestyle.gtimg.cn%2F
qzonestyle%2Fact%2Fqzone_app_img%2Fapp613_613_75.png%26openid%3D0000000000000000000000000E111111%26
openkey%3D1111806DC5D1C52150CF405E42222222%26payitem%3D50005%2A4%2A1%26pf%3Dqzone%26
pfkey%3D1B59A5C3D77C7C56D7AFC3E2C823105D%26ts%3D1333674935%26zoneid%3D0


生成sig时构造的密钥为:12345f9a47df4d1eaeb3bad9a7e54321&


生成的签名为: IC0ErTY2gpTbNq8f1hbh0tSu1CM=


URL编码前的请求: https://119.147.19.43/v3/pay/buy_goods?amt=4&appid=600&appmode=1&format=json&
goodsmeta=道具*测试描述信息!!!&
goodsurl=http://qzonestyle.gtimg.cn/qzonestyle/act/qzone_app_img/app613_613_75.png&
openid=0000000000000000000000000E111111&openkey=1111806DC5D1C52150CF405E42222222&payitem=50005*4*1&
pf=qzone&pfkey=1B59A5C3D77C7C56D7AFC3E2C823105D&ts=1333674935&zoneid=0&sig=IC0ErTY2gpTbNq8f1hbh0tSu1CM=


URL编码后的请求: https://119.147.19.43/v3/pay/buy_goods?amt=4&appid=600&appmode=1&format=json&
goodsmeta=%E9%81%93%E5%85%B7%2A%E6%B5%8B%E8%AF%95%E6%8F%8F%E8%BF%B0%E4%BF%A1%E6%81
%AF%EF%BC%81%EF%BC%81%EF%BC%81&goodsurl=http%3A%2F%2Fqzonestyle.gtimg.cn%2Fqzonestyle
%2Fact%2Fqzone_app_img%2Fapp613_613_75.png&openid=0000000000000000000000000E111111&
openkey=1111806DC5D1C52150CF405E42222222&payitem=50005%2A4%2A1&pf=qzone&pfkey=1B59A5
C3D77C7C56D7AFC3E2C823105D&ts=1333674935&zoneid=0&sig=IC0ErTY2gpTbNq8f1hbh0tSu1CM%3D


2.7 返回参数说明

参数名称 描述
ret 私有返回码说明如下:

1001:请求参数错误;
1059:TOKEN超时;
1060:订单已回滚;
1061:订单已确认;
1099:系统繁忙。
公共返回码详见公共返回码说明#OpenAPI V3.0 返回码
注意支付API接口返回-5错误通常是由于sig生成错误引起的,请根据腾讯开放平台第三方应用签名参数sig的说明详细检查sig的生成是否正确。

msg 如果错误,返回错误信息。

is_lost 判断是否有数据丢失。如果应用不使用cache,不需要关心此参数。

0或者不返回:没有数据丢失,可以缓存。
1:有部分数据丢失或错误,不要缓存。

token 有3种含义:

(1)交易的token号(ret=0时才保存,token长度不超过64个字符)。
在后续的扣费成功后调用应用的发货接口时会将token传给应用,作为本次交易的标识。
注意,交易的token有效期为15分钟,必须在15分钟内将token传给应用来调用发货接口,否则将会返回流水号不存在的错误。
(2)订单的token号(ret=0时才保存,token长度不超过64个字符)。
应用如果调用发货确认接口,则需要传递该token号,作为本次订单的标识。
注意,订单的token有效期为2个小时,必须在2个小时内传递该token,否则将会返回订单无效的错误。
(3)抽奖送礼包单笔消耗送礼包营销活动中,领取道具/物品需要的token号。
用户消耗Q点成功后,腾讯后台回调赠送道具发货URL时,需要传递该token号。
注意,领取道具/物品的token有效期为72小时,必须在72个小时内传递该token,否则将会返回token不存在的错误。

url_params ret为0的时候,返回真正购买物品的url参数。
在下一步调用前端JS API时,应用需要将url_params传递过去,以便在支付窗口中显示具体的购买物品的数量以及应付金额(如服务后台会针对腾讯朋友或QQ空间平台的应用,对黄钻用户进行8折优惠的处理),让用户完成支付操作。

2.8 正确返回示例

JSON示例:

Content-type: text/html; charset=utf-8
{
"ret":0,
"is_lost":0,
"url_params": "v1/m01/10227/pay/buy_goods?token_id=4021A324754CCD7EA01836261D0AFF7207622&sig=5b9feed5b43b8f8f829d19fb489814e4",
"token": "4021A324754CCD7EA01836261D0AFF7207622"
}

2.9 错误返回示例

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

相关文档

下一步: fusion2.dialog.buy

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

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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部