开发指南
一、虚拟充值附录
失败代码
代码 |
含义 |
备注 |
0101 |
缺少必需参数 |
缺少必选参数 |
0102 |
签名失败 |
SDK签名验证失败 |
0103 |
参数有误，参数格式或值非法 |
该错误在淘宝接收异步结果返回时使用，商家请不要使用 |
0104 |
找不到对应的订单 |
|
0302 |
购买数量非法 |
当购买数量小于最低限额，大于最高限额，或者不满足特定数量要求 |
0303 |
商品库存不足 |
商家商品库存不足 |
0304 |
商品维护中 |
商家正在维护商品，商品暂时不可用 |
0305 |
找不到对应的商品 |
商家无法根据淘宝发送的cardId、gameId、section1、section2定位到自己的商品，可能是对应关系不正确 |
0306 |
参数有误，被充值帐户有误，比如联通充值时输入了移动的号码，QQ充值时输入字母 |
参数格式或值非法，账户有误或者不支持，注意和0502的区别 |
0501 |
厂商例行维护，无法充值 |
|
0502 |
被充值帐户有误，比如联通充值时输入了移动的号码，QQ充值时输入字母 |
注意和0306的区别 |
0503 |
充值失败 |
厂商返回的充值失败，如未退出游戏无法充值等 |
0701 |
非法的订单状态转换 |
该错误一般在淘宝接收异步结果返回时使用 |
0901 |
充值超时，订单被取消 |
|
0902 |
请求超时 |
SDK中校验时间超时 |
… |
… |
|
5013 |
用户未实名认证 |
需要先完成实名认证 |
5014 |
未成年人限制购买 |
18周岁以下未成年人限制购买此类商品 |
5019 |
账号未绑定支付宝 |
先绑定支付宝账号后再下单 |
5020 |
账号禁止下单 |
联系淘宝客服处理 |
5021 |
有多笔未支付订单 |
有多笔未支付订单，无法充值，先处理之后才能继续下单 |
5023 |
订单重复 |
请检查传递的outOrderId是否唯一，同样的outOrderId会被当做同一笔订单处理 |
9999 |
未知错误 |
生产环境避免出现该错误 |
订单状态
状态和失败代码是对应的，比如0502只能出现在FAILED状态中，不能出现在ORDER_FAILED状态中
代码 |
含义 |
失败代码可能值 |
备注 |
ORDER_FAILED |
商家订单创建失败，淘宝会退款给买家 |
0104、0302、0303、0304、0305、0306、5013、5014、5019、5020、5021、5023… |
订单完结状态 |
CANCEL |
订单取消，淘宝会退款给买家 |
0901 |
订单完结状态 |
SUCCESS |
充值成功，用户帐户已获得充值 |
N/A |
订单完结状态 |
UNDERWAY |
充值中，厂商已接受请求，但未返回成功充值结果；或代表一个临时性的可短时间恢复的错误。 |
N/A |
订单中间状态 |
FAILED |
商家订单创建成功，但充值失败，且无法重试，淘宝会退款给买家 |
0501、0502、0503 … |
订单完结状态 |
GENERAL_ERROR |
请求失败，任何签名错误、缺少必要参数等的协议类错误，都应该返回该类错误 |
0101、0102、0301、0902… |
通用错误 |
直冲订单状态：
0 初始
1未下单,
2已下单
3充值成功,待转交易,
4充值成功,转交易成功,
5充值失败,待退款
6充值失败,退款成功
7充值取消,待退款
8充值取消,退款成功
交易订单状态(资金状态)
1 未冻结/未付款 -> 等待买家付款
2 已冻结/已付款 -> 等待卖家发货
4 已退款 -> 交易关闭
6 已转交易 -> 交易成功
7 没有创建外部交易(支付宝交易)
8 交易被淘宝关闭
接口交互字段相关类型长度
字段名 |
字段类型 |
长度 |
备注 |
CARD_ID |
VARCHAR2 |
256 |
|
GAME_ID |
NUMBER |
22 |
|
FIRST_SECTION_ID |
NUMBER |
22 |
|
SECOND_SECTION_ID |
NUMBER |
22 |
|
QUANTITY |
NUMBER |
22 |
|
tbOrderNo |
NUMBER |
22 |
|
coopId |
NUMBER |
22 |
|
customer |
VARCHAR2 |
256 |
|
COOP_ORDER_SNAP |
VARCHAR2 |
512 |
二、FAQ
控制台配置相关
请参考：配置链路常见问题
前端下单
1. 调用my.tb.virtualTrade，提示：温馨提醒，请勿重新下单
检查outOrderId的传值是否重复，平台侧针对同一个outOrderId，会认为是同一笔订单，后使用该值下单的订单会报错阻断。
2. 提示：e_code":3038,"err_message":"当前应用暂不支持购买商品"，怎么处理？
检查是否完成虚拟直充相关的配置，相关配置过程可参考文档：店铺商品发布&绑定小游戏。
3. 提示：订单创建失败，error：3037，怎么处理？
检查支付下单的商品是否上架，保证商品上架后进行下单测试。具体配置请参考：店铺商品发布&绑定小游戏。
4. 订单如何关联到多角色和多游戏区？
不支持接口原始参数维度的区服设置，但可以通过外部订单id关联：outOrderId关联区服信息，该参数会在奇门充值请求里，透传带到服务端。详细过程，请参考文档 ：【前端】拉起下单页&消费者支付接口。
5. 提示：my.tb.virtualTrade is not a function，怎么处理？
检查是否在IDE创建的项目是【小游戏-新】，如果使用的是【小游戏】没有这个接口。
奇门充值对接
1. 调用taobao.game.charge.zc.order接口，提示：请求未接收到充值回调，怎么处理？
接口和应用都需要在平台完成发布上线，运营配置后，后才能被线上调用。
2. outOrderId的值不是开发者设置的值，怎么处理？
如果是较早注册的小游戏，联系雏田处理。
3. 控制台奇门API接口测试
直充接口测试目的：测试商家接口可行性、规范性的基本要求
1) 冒烟测试：冒烟测试只是测试TOP是否可以调通你的服务，你的服务返回内容是否正常，返回内容是否可以正常解析这里都是不能测出来的。
2) 编码测试：验证返回的编码是否为GBK，如果不是则测试失败，也是不能测试返回结果是否格式正常。
3) 签名测试：这个测试TOP会故意把签名弄错，商家需检测出来，商家服务使用sdk测试签名时返回False。商家需要返回签名错误的结果，其中错误类型为GENERAL_ERROR，错误码为0102（见附录）因此，服务需要返回如下的内容：（针对query），其他的order和cancel最外面的gamezctopquery不同。
填写测试地址时出现报错：javax.net.ssl.SSLHandshakeException:java.security.cert.CertificateException: Certificates does not conform to algorithm constraints
HTTPS地址网络协议异常，建议更换为http协议或更换接口域名或地址
下单接口可以测试通过，查询接口不给通过为什么？
核实外围标签：下单接口标签</gamezctoporder>，查询接口标签：</gamezctopquery>
具体差别看接口的虚拟直充开发文档。
直充接口测试签名不通过：
可以参考签名方式详情：《签名校验》节
//open.alitrip.com/docs/doc.htm.htm?spm=a219a.7386653.6.3.W9xNVM&treeId=1&articleId=103784&docType=1
需要注意，HTTP请求中的URL参数编码字符集、字符串转字节流进行MD5摘要时的字符集要保持一致，否则会导致含中文参数的签名与TOP不一致。直充编码用的GBK。
直充接口完成平台测试了，调用小程序下单没有收到请求？
请逐步排查：
1）接口是否为线上运行分钟状态，如图：
2）通过开放平台上日志工具进行查看淘宝调用请求，查询具淘宝请求和响应内容
日志查看地址：https://work.open.taobao.com/qimenLogQueryTools
3）是否使用正常淘宝用户下单，店铺账号和异常账号不可进行下单测试
取消充值接口有什么作用
取消接口不是商家取消订单使用的，取消接口全称是“超时退款通知接口”，该接口只有在超时退款场景下触发，用于告知商家订单已经退款，不要再进行后续充值，避免资损发生，用户申请售后时，不会调用该接口。
下单接口会重试吗？重试频率是多少？
答：下单接口会重试，重试时间随着订单时间增加而间隔增长
大致参考时间为：3,3,3,5,5,10,10分钟间隔这种频率递增，具体间隔时间以接口请求时间为准
返回参数必须使用xml吗？可以使用json吗？
必须使用xml，而且需要严格返回参数值
直充接口是什么方式请求的？是否直充其他请求方式
直充接口都是以get方式发送请求的，不支持其他请求方式
接口响应时间是多少?
答：一般是要求1秒内响应，最大超时为5秒（建议在1秒内）
接口测试发布上线了，但是没有请求到我服务器
可以通过开放平台上的日志工具进行查看，淘宝调用请求记录参考：https://work.open.taobao.com/qimenLogQueryTools
查询淘宝发送请求（大概几分钟延迟）
接口正常响应了SUCCESS，但是订单没有交易成功是为什么？
1）通过日志工具查看接口是否响应超时
2）检查coopOrderSuccessTime字段是否正常返回，是要求14位，详见接口文档
直充接口中的区服信息怎么获取
小程序链路不支持传原始参数维度的区服信息。但可以通过外部订单id关联：outOrderId关联区服信息，该参数会在奇门充值请求里，透传带到服务端。
