充值接口文档V1.7.docVIP

充值接口文档 V1.7 2008-06-25 xinglie 版本 修改内容 时间 V1.5 修改单词faield为failed 2008-6-25 V1.6 对failedCode0306做了些解释 2008-7-30 V1.7 添加对账接口功能说明，充值接口状态说明 2009-12-28 一、基本约定 二、外部系统需要实现的接口 三、淘宝需要实现的接口 四、附录 一、基本约定 如果某个变量没有值，那么该变量的key和value对将不出现在请求的URL和加密明文中，请求URL中的value必须经过URLEncode(GBK编码)，加密明文为 key1value1key2value2...PRIVATEKEY， 其中，key以字母升序排列，value为未encode之前的原值，“…”为更多的keyvalue对，PRIVATEKEY为密文，最后组合成的待加密明文应无空格，加密方式为MD5，可以使用Jakarta/commons/codec 返回结果统一使用xml，其中参数Element，如果没有值，则返回空标签。 淘宝订单和合作商订单一一对应。 当直充接口一段时候内无任何同步返回时，淘宝系统会定时调用查询接口向合作商发起查询，如果发现合作商没有收到淘宝的下单REQUEST_FAILED[failedCode=0104]，会使用同样的参数再次发起直充请求。合作商必须针对可能存在的相同淘宝订单号的重复请求做控制。 合作商应该尽快处理UNDERWAY状态的订单，使其要么成功，要么失败。对于超过1小时仍然处于UNDERWAY的订单，淘宝将通过订单取消接口向合作商发起订单取消，如果合作商确认订单取消，则应该返回CANCEL，淘宝接收到CANCEL后将会为买家退款，如果因为运营商原因，合作商无法决定是否取消订单，仍可以返回UNDERWAY，淘宝将继续调用该接口请求取消，除非返回SUCCESS、CANCEL、FAILED状态，如果超过100分钟 ，仍然为UNDERWAY状态，淘宝将默认取消相应订单，然后为买家退款，并不再进行任何接口通知。 商品信息快照记录了商品成交时的样子，为合计金额和cardId、gameId、section1、section2四个字段对应中文名称字符串的组合，用”|”号隔开，快照信息不应该在业务逻辑中使用，仅用于记录日志保存以备查。淘宝所传的快照应为淘宝数据库中的信息，合作商所传的快照应为合作商数据库中的信息。 发生任何签名错误、缺少必要参数等的协议类错误时，合作商应该返回[REQUEST_FAILED]错误，除基本约定4外淘宝接收到REQUEST_FAILED后均不做任何处理，会定时再次发出之前的请求，所以除基本约定4外，REQUEST_FAILED不应该在生产环境上出现，在测试阶段应全部解决。详见附录：订单状态。 任何外部系统接口一旦返回终结状态，如果淘宝还接收到相应订单的其他状态，都一律不接受。 【注意】无论是淘宝主动查询外部商家订单状态 还是 外部商家异步通知淘宝订单状态 还是 外部商家充值接口返回的订单状态，只要外部商家返回的状态是“终结状态”，淘宝就会认为订单完结，直接转支付宝交易 或者 直接退款给买家，订单状态不能再发生变更；比如淘宝查询时返回“failed”，但是后来外部商家又异步通知订单为“success”，淘宝是不会处理后面的“success”的；“订单完结状态”和“订单中间状态”定义看最后面 二、外部系统需要实现的接口 直充接口： 请求地址样例 http://host:port/resource?coopId=xxxtbOrderNo=xxxcardId=xxxcardNum=xxxcustomer=xxxsum=xxxgameId=xxxsection1=xxxsection2=xxxnotifyUrl=xxxsign=xxxversion=xxx 请求参数说明 参数 说明 是否必选 参数类型 加密字段 备注 coopId 商家编号 必选 String 是 tbOrderNo 淘宝的订单号 必选 String 是 cardId 充值卡商品编号 必选 String 是 需要合作商自己维护对应关系 cardNum 充值卡数量 必选 String 是 customer 被充值帐号或手机号码 必选 String 是 sum 本次充值总金额，代表用户支付的金额 必选 String 是 单位为元，如200.00代表200.00元 gameId 充值游戏编号 可选 String 是 需要合作商自己维护对应关系 section1 游戏或手机区 可选 String 是 需要合作商自己维护对应关系 section2 二级分类，如游戏服 可选 String 是 需要合作商