v3/pay/exchange_goods

特别声明

1. 本接口仅适用于有寄售系统,且在支付接入中提交寄售接入申请并审核通过的应用。使用前请确保你的应用具有该OpenAPI的访问权限。
2. 本接口需要使用HTTPS协议访问。

目录

1 功能说明

用户进入应用中的寄售系统,选择要购买的道具,点击“购买”按钮后,应用调用该接口发送请求,以获取本次交易的token,以及购买物品的url参数。

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

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

2 接口调用说明

2.1 URL

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

正式环境域名或测试环境IP详见:API3.0文档#请求URL说明
注意:本接口需要使用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 表示购买的所有物品的总价格,即物品的单价*数量(以游戏币为单位)。

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

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

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

payitem 必须 string 物品购买信息。

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

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。此时调用本支付接口时,必须回传该参数。
buy_type 必须 string 道具购买类型,请输入固定值:100。
fee 必须 string 应用扣除的佣金。取值范围为[0, amt对应的值]。

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

seller_openid 必须 string 道具寄售系统中,售卖道具的用户的openid。
cee_extend string 部署在CEE_V2的应用,必须传入该参数,该参数不参与签名计算

详见:CEE_V2访问云支付

2.6 请求示例

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

method:GET
url_path:/v3/pay/exchange_goods
假设appkey为:56abfbcd12fe46f5ad85ad9f2faf36d7

请求参数包括:
amt:10
appid:15499
buy_type:100
fee:2
format:json
goodsmeta:10金币*泰坦之怒10金币礼包
(注: goodsmeta的值必须是是UTF8格式的字符。
2012年8月3日起,无需对字符进行Base64编码,该变化向前兼容,即以前接入的应用如果对字符进行了Base64编码也不受影响)
goodsurl:http://qzonestyle.gtimg.cn/qzonestyle/act/qzone_app_img/app613_613_75.png
openid:00000000000000000000000014BDF6E4
openkey:A92245EFAB90DAA55F9B8415CF7255F4
payitem:50005*2*5
pf:qzone
pfkey:A6030BF20A936D69DFBDD875768B0F05
seller_openid:000000000000000000000000008FA509
ts:1345000483
zoneid:1

则生成sig时构造的源串为:GET&%2Fv3%2Fpay%2Fexchange_goods&amt%3D10%26appid%3D15499%26buy_type%3D100%26fee%3D2%26
format%3Djson%26goodsmeta%3D10%E9%87%91%E5%B8%81%2A%E6%B3%B0%E5%9D%A6%E4%B9%8B%E6%80%9210%E9%87%91%E5%B8%81%E7%A4%
BC%E5%8C%85%26goodsurl%3Dhttp%3A%2F%2Fqzonestyle.gtimg.cn%2Fqzonestyle%2Fact%2Fqzone_app_img%2Fapp613_613_75.png%26
openid%3D00000000000000000000000014BDF6E4%26openkey%3DA92245EFAB90DAA55F9B8415CF7255F4%26payitem%3D50005%2A2%2A5%26
pf%3Dqzone%26pfkey%3DA6030BF20A936D69DFBDD875768B0F05%26seller_openid%3D000000000000000000000000008FA509%26
ts%3D1345000483%26zoneid%3D1

生成sig时构造的密钥为:56abfbcd12fe46f5ad85ad9f2faf36d7&

生成的签名为: CAOtp7gU0PI/t257EKnqPFKwPJ4=

URL编码前的请求:
https://119.147.19.43/v3/pay/exchange_goods?amt=10&appid=15499&buy_type=100&fee=2&format=json&
goodsmeta=10金币*泰坦之怒10金币礼包&goodsurl=http://qzonestyle.gtimg.cn/qzonestyle/act/qzone_app_img/app613_613_75.png
&openid=00000000000000000000000014BDF6E4&openkey=A92245EFAB90DAA55F9B8415CF7255F4&payitem=50005*2*5&
pf=qzone&pfkey=A6030BF20A936D69DFBDD875768B0F05&seller_openid=000000000000000000000000008FA509&
ts=1345000483&zoneid=1&sig=CAOtp7gU0PI/t257EKnqPFKwPJ4=


URL编码后的请求:
https://119.147.19.43/v3/pay/exchange_goods?amt=10&appid=15499&buy_type=100&fee=2&format=json&
goodsmeta=10%E9%87%91%E5%B8%81*%E6%B3%B0%E5%9D%A6%E4%B9%8B%E6%80%9210%E9%87%91%E5%B8%81%E7%A4%BC%E5%8C%85&
goodsurl=http%3A%2F%2Fqzonestyle%2Egtimg%2Ecn%2Fqzonestyle%2Fact%2Fqzone%5Fapp%5Fimg%2Fapp613%5F613%5F75%
2Epng&openid=00000000000000000000000014BDF6E4&openkey=A92245EFAB90DAA55F9B8415CF7255F4&payitem=50005*2*5&
pf=qzone&pfkey=A6030BF20A936D69DFBDD875768B0F05&seller_openid=000000000000000000000000008FA509&
ts=1345000483&zoneid=1&sig=CAOtp7gU0PI%2Ft257EKnqPFKwPJ4%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,否则将会返回订单无效的错误。

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

2.8 正确返回示例

JSON示例:

Content-type: text/html; charset=utf-8
{
"ret":0,
"is_lost":0,
"url_params": "v1/m01/10227/pay/exchange_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.

腾讯公司 版权所有

有问必答 返回顶部