v3/pay/confirm_delivery

目录

What's New?

2012年11月13日,本接口从原有的推荐调用,改为必须调用。
2012年9月27日,支付接入增加寄售模式,本接口可用于Q点直购道具和道具寄售两种场景。

1. 使用前必读

腾讯支付后台设置的调用第三方发货超时是2秒钟,如果应用发货时间超过该限制,将造成腾讯支付后台取消用户扣款而应用发货服务器继续发货的风险,带来收入损失。

为规避该风险,请开发者务必做到下列几项:
1. 因此所有应用接入支付时都必须调用本接口,如果因为没有调用本接口而造成的收入损失,将由开发者自己承担。
-如果是新接入支付的应用,在应用上线支付前必须实现对本接口的调用。
-如果是已经接入支付的应用,请进行代码改造以实现对本接口的调用。

2. 请开发者配置支付告警信息,及时获得异常情况。详见:告警服务#5. 告警接收人配置

2. 接口原理说明

调用本接口后,腾讯支付后台的处理方式如下:
1. 当腾讯支付后台在2秒内收到第三方应用的发货响应,则直接展示交易结果,交易成功的话则立刻完成扣款,交易结束。

2. 当腾讯支付后台检测到第三方发货超过2秒时:
(1)腾讯支付后台不会立刻认为交易失败,而是将交易暂时挂起,同时冻结用户本次支付的金额,并提示用户交易进行中。如下图所示:
注:界面上提示“交易进行中”主要是为了让界面更友好,原因还需要具体分析,看到底是发送超时还是接受超时。
回调发货要经过公网,可能的超时包括发送超时及接受超时两种情况。对于发送超时(可能是由于接入支付时填错了发货IP导致的),第三方应用会收不到发货请求,同时腾讯后台系统提示用户交易进行中。

confirm_delivery.png
(2)此后腾讯支付后台等待第三方应用的发货通知。应用在进行发货后应该调用本接口通知腾讯后台已经发货。如果最终发货成功,则完成扣款,否则不扣款。

3. 使用时的注意事项

在调用该接口前,请务必注意如下事项:

关注点 注意事项
调用时间 1. 本接口必须在回调发货处理完成,发完货后再发起,即异步实现。例如发完货后存储一条记录,扫描到有发完货的记录,就调用本接口通知发货结果。
2. 腾讯支付后台回调发货URL后,等待发货通知的最长时间为5分钟,如果超出5分钟后收到发货通知,则认为交易失败。(第三方收到回调发货信息后,2秒内执行发货并返回发货结果{"ret":0,"msg":"OK"}给平台,然后在10秒左右调用本接口来再次通知平台发货的结果)。本接口的调用时间为第三方收到回调2秒后,5分钟之内,平台建议最佳时间为10秒左右。
 
调用次数 3. 由于应用无法得知腾讯支付后台是否在2s内收到应用成功发货的返回,故需要对每一次发货都进行结果通知。

为避免通知失败,本接口可以重复调用,直到收到腾讯支付侧的响应。

 
返回结果 4. 本接口通知的发货结果(即参数provide_errno)必须和回调发货时的响应结果(即回调发货接口的返回码ret)一致,否则会被腾讯支付系统认为本笔交易异常。
5. 该接口只是通知接口,返回结果只表明腾讯支付侧是否收到发货结果,最终的支付结果请以提供的账单为准。
6. 每笔交易是否扣款都是以回调发货的返回错误码为依据,仅发货超时和返回信息格式不合法会触发平台挂起订单,此时需要调用本接口通知发货结果。
7. 发完货后通知发货结果仅为一个补通知的环节,平台交易以回调发货时的响应结果为准,且异步通知发货结果仅对已挂起的订单起作用,如果在回调发货时交易就结束,即使通知发货结果也不能改变订单状态。
 
其它 8. 回调发货返回成功,而通知发货结果时告知平台发货失败,被视为有假发货嫌疑,订单不会改变状态,交易成功。
9. 回调发货失败多次,会触发平台的锁定策略,可能导致收入受损,请尽可能提高回调发货的成功率。

4. 接口调用说明


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

本接口属于以下流程中的第10步:
unipay_4.png

二:道具寄售模式-道具寄售
本接口属于道具寄售流程中的第10步:
exchange_goods.png

4.1 URL

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

正式环境域名或测试环境IP详见:API3.0文档#请求URL说明

注:本接口需要使用HTTPS协议访问。

4.2 格式

json

4.3 HTTPS请求方式

GET, POST

4.4 IP限制

TRUE

4.5 输入参数说明

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

(1)公共参数
发送请求时必须传入公共参数,详见公共参数说明
注:
本接口的公共参数“openkey”为可选;
对于公共参数“pf”,如果解析CanvasURL时获取不到pf,可传入“pengyou”或“qzone”。

(2)私有参数

参数名称 是否必须 类型 描述
ts 必须 string linux时间戳。

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

payitem 必须 string 物品信息。

通过解析腾讯后台回调发货URL时传入的payitem获得该参数的值。

token_id 必须 string 应用调用v3/pay/buy_goods接口成功返回的订单token。

注意,订单token的有效期为2个小时,必须在获取到订单token后的2个小时内传递该token,否则将会返回订单无效的错误。

billno 必须 string 支付流水号(64个字符长度。该字段和openid合起来是唯一的)。

通过解析腾讯后台回调发货URL时传入的billno获得该参数的值。

version string 协议版本号。

通过解析腾讯后台回调发货URL时传入的version获得该参数的值。

zoneid 必须 string 支付接入页面配置的分区ID。

通过解析腾讯后台回调发货URL时传入的zoneid获得该参数的值。
注:2013年后接入的寄售应用,此参数将作为分区发货的重要参数,如果因为参数传错或为空造成的收入损失,由开发商自行承担。

providetype string 发货类型,这里请传入0。

0表示道具购买,1表示每日礼包营销活动中的道具赠送,2表示交叉营销任务集市中的奖励发放。
通过解析腾讯后台回调发货URL时传入的providetype获得该参数的值。

provide_errno 必须 string 发货结果,0:表示发货成功,其他:表示失败。

输入的值请务必与回调发货URL时的返回码ret的值一致,否则会被腾讯支付系统认为本笔交易异常

provide_errmsg string 发货结果描述,最长为128字节。
amt 必须 string Q币Q点消耗金额或财付通游戏子账户的扣款金额。

通过解析腾讯后台回调发货URL时传入的amt获得该参数的值,如果回调URL中没有参数amt,则这里传入0。

payamt_coins 必须 string 扣取的游戏币总数,单位为Q点。

通过解析腾讯后台回调发货URL时传入的payamt_coins获得该参数的值,如果回调URL中没有参数payamt_coins,则这里传入0。

pubacct_payamt_coins string 扣取的抵用券总金额,单位为Q点。可以为空,若传递空值或不传本参数则表示未使用抵扣券。

通过解析腾讯后台回调发货URL时传入的pubacct_payamt_coins获得该参数的值,如果回调URL中没有参数pubacct_payamt_coins,则这里传入0。

4.6 请求示例

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

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


请求参数包括:
amt:4
appid:15499
billno:-APPDJT18700-20120210-1428215572(计算sig时,本接口billno中的“-”符号无需转换成%2D)
openid:00000000000000000000000014BDF6E4
openkey:8A590068198AA8F91EADDCC408215AD6
payamt_coins:2
payitem:5005*4*1
pf:qzone
provide_errno:0
providetype:0
pubacct_payamt_coins:1
token_id:70CA63F0AD33AD19FD376DDC4792337A04621
ts:1339409927
version:v3
zoneid:0


则生成sig时构造的源串为:
GET&%2Fv3%2Fpay%2Fconfirm_delivery&amt%3D4%26appid%3D15499%26billno%3D-APPDJT18700-20120210-1428215572%26openid%3D00000000000000000000000014BDF6E4%26openkey%3D8A590068198AA8F91EADDCC408215AD6%26
payamt_coins%3D2%26payitem%3D5005%2A4%2A1%26pf%3Dqzone%26provide_errno%3D0%26providetype%3D0%26
pubacct_payamt_coins%3D1%26token_id%3D70CA63F0AD33AD19FD376DDC4792337A04621%26ts%3D1339409927%26
version%3Dv3%26zoneid%3D0


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


生成的签名为: vNeJhiSqdPXOH6/0pH4yfRHrQhE=


URL编码前的请求:http://119.147.19.43/v3/pay/confirm_delivery?
amt=4&appid=15499&billno=-APPDJT18700-20120210-1428215572&
openid=00000000000000000000000014BDF6E4&openkey=8A590068198AA8F91EADDCC408215AD6&
payamt_coins=2&payitem=5005*4*1&pf=qzone&provide_errno=0&
providetype=0&pubacct_payamt_coins=1&token_id=70CA63F0AD33AD19FD376DDC4792337A04621&ts=1339409927&
version=v3&zoneid=0&sig=vNeJhiSqdPXOH6/0pH4yfRHrQhE=


URL编码后的请求:http://119.147.19.43/v3/pay/confirm_delivery?
amt=4&appid=15499&billno=-APPDJT18700-20120210-1428215572&
openid=00000000000000000000000014BDF6E4&openkey=8A590068198AA8F91EADDCC408215AD6&
payamt_coins=2&payitem=5005*4*1&pf=qzone&provide_errno=0&
providetype=0&pubacct_payamt_coins=1&token_id=70CA63F0AD33AD19FD376DDC4792337A04621&ts=1339409927&
version=v3&zoneid=0&sig=vNeJhiSqdPXOH6%2F0pH4yfRHrQhE%3D

4.7 返回参数说明

参数名称 描述
ret 返回码。由于本接口只是通知接口,返回结果只表明腾讯支付侧是否收到发货结果,最终的支付结果请以提供的账单为准。

私有返回码说明如下:

错误码 含义说明 订单回滚 交易成功 扣款成功
1001 请求参数错误。

操作指引: 根据“4.5 输入参数说明”检查传的参数是否正确。

1059 TOKEN超时(确认的订单必须是2个小时内的订单,否则返回该错误码)。

操作指引: 根据v3/pay/buy_goods接口token含义说明排查token。

1060 订单已回滚。

操作指引:交易失败,无需后续操作。

1062 通知过早订单尚未挂起,请稍候再试(收到发货回调后,2秒内应答,2秒后才调用此接口,可等待几秒后,重复通知)。

操作指引:可重试3次,还是挂起检查调用该接口时间,确认时间无误请求三次放弃此订单。

1063 订单不存在。

操作指引:系统错误,记录日志,需要后续对账。

1068 交易已失败结束,通知过晚(未扣款)。

操作指引:交易失败,无需后续操作。(调用确认接口的时候需要注意调用时间,严格按照“3. 使用时的注意事项”规定时间调用。)

1069 交易已成功结束,通知过晚(已扣款)。

操作指引:交易成功,无需后续操作。

1099 系统繁忙,请稍候再试(可等待几秒后,重复通知)。

操作指引:可重试3次,三次后还出现放弃此订单。


公共返回码详见公共返回码说明#OpenAPI V3.0 返回码
注意支付API接口返回-5错误通常是由于sig生成错误引起的,请根据腾讯开放平台第三方应用签名参数sig的说明详细检查sig的生成是否正确。

msg 发货确认操作的结果,成功为“OK”,表示发货已成功。

如果发货失败,返回错误信息。

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

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

4.8 正确返回示例

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

4.9 错误返回示例

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

相关文档

一:Q点直购模式 / 道具寄售模式-直购应用道具 / 道具寄售模式-游戏币快捷支付,请使用本上下步导航:
上一步:回调发货URL的协议说明 V3

二:道具寄售模式-道具寄售,请使用本上下步导航:
上一步:回调道具交换URL的协议说明


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

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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部