福禄API对接文档
  1. 接口规范
  • 产品介绍
  • 快速指引
    • API应用操作说明
    • 对接流程
    • 商品模版指引说明
    • 测试环境模拟数据
    • 常见问题
  • 接口规范
    • 签名规则
    • 卡密解密说明
    • 返回码说明
    • 免责声明
  • 业务场景
    • 在线直充
    • 话费充值
    • 卡密采购
  • API列表
    • 商品API
      • 获取商品列表接口 fulu.goods.list.get
      • 获取商品信息接口 fulu.goods.info.get
      • 获取商品模板接口 fulu.goods.template.get
      • 商品库存校验接口 fulu.goods.stock.check
    • 订单API
      • 直充下单接口 fulu.order.direct.add
      • 卡密下单接口 fulu.order.card.add
      • 话费下单接口 fulu.order.mobile.add
      • 订单查询接口 fulu.order.info.get
      • 订单扩展信息查询接口 fulu.order.extend.get
    • 商户API
      • 获取商户信息接口 fulu.user.info.get
    • 其他API
      • 对账单申请接口 fulu.order.record.get
      • 手机号归属地查询接口 fulu.mobile.info.get
    • 回调通知
      • 订单充值结果回调
      • 售后退款状态回调
      • 商品信息变动回调
      • 对账单通知回调
      • 订单充值结果回调-在线调试
      • 售后退款状态回调-在线调试
      • 商品信息变动回调-在线调试
    • 特殊品类API
      • 微信红包
        • 订单充值结果回调
        • 微信红包直充下单接口 fulu.order.direct.addredpacket
        • 微信红包订单查询接口 fulu.order.info.getredpacket
  1. 接口规范

返回码说明

公共返回码#

返回码返回码描述解决方案
0接口调用成功接口调用成功，按正常流程处理；下单接口中，接口调用成功表示下单成功，但是下单成功不表示订单充值成功，要想获得订单的充值结果，需要调用查单接口来获得订单充值状态。
1000必须传入API接口名称错误原因：
接口请求时method参数不能为空，必须传入API接口名称参数；
解决方案：
1、在开放平台在线调试获取模拟请求参数，进行方法名比对；
1001无效的API接口名称错误原因：
接口请求时method接口名称错误或不存在；
解决方案：
1、以开放平台具体接口的method为准，替换请求参数中method的接口名称；
1002必须传入时间戳错误原因：
接口请求时timestamp参数不能为空，必须传入时间戳参数；
解决方案：
1、在请求接口中填入timestamp参数（格式为：yyyy-MM-dd HH:mm:ss）；
1003时间戳格式错误错误原因：
接口请求时timestamp参数格式不正确；
解决方案：
1、时间戳格式为：yyyy-MM-dd HH:mm:ss，请按要求传入参数；
1004时间戳已超过有效期错误原因：
接口请求时服务器会校验请求参数的时间戳timestamp，该参数与服务器当前时间误差不能超过10分钟；
解决方案：
1、请检查入参时间戳字段是否是当前请求时间（不建议同一个包体重复请求）；
2、检查请求方服务器时间是否与北京时间同步；
1005必须传入app_key错误原因：
接口请求时app_key参数不能为空，必须传入app_key参数；
解决方案：
1、在请求接口中填入app_key参数(生产环境：商户控制台->应用配置->密钥管理 沙箱环境参数获取)；
1006无效的app_key错误原因：
接口请求时服务器会校验请求参数的app_key，判断当前app_key是否有效；
解决方案：
1、检查appkey是否复制错误；
2、沙箱环境与生产环境数据不互通；
3、测试环境只能使用测试数据，测试环境数据获取地址：测试环境模拟数据；
1007必须传入版本号错误原因：
接口请求时version参数不能为空，必须传入版本号；
解决方案：
1、目前的版本号参数值为：2.0；
1008版本号错误错误原因：
接口请求时version参数值错误；
解决方案：
1、目前的版本号参数值为：2.0；
1009必须传入format格式错误原因：
接口请求时format参数不能为空，必须传入format格式参数；
解决方案：
1、目前的format格式仅支持json；
1010format格式错误错误原因：
接口请求时format参数值错误；
解决方案：
1、目前的format格式仅支持json；
1011必须传入编码格式错误原因：
接口请求时charset参数不能为空，必须传入charset编码格式参数；
解决方案：
1、目前的charset编码格式仅支持utf-8；
1012编码格式错误错误原因：
接口请求时charset参数值错误；
解决方案：
1、目前的charset编码格式仅支持utf-8；
1013必须传入签名加密类型错误原因：
接口请求时sign_type参数不能为空，必须传入签名加密类型；
解决方案：
1、目前的sign_type签名加密类型支持md5和rsa；
1014签名加密类型错误错误原因：
接口请求时sign_type参数值错误；
解决方案：
1、目前的sign_type签名加密类型支持md5和rsa；
1015必须传入签名错误原因：
接口请求时sign参数不能为空，必须传入签名参数；
解决方案：
1、在请求接口中填入sign参数；
1016签名错误错误原因：
接口请求时服务器会校验请求参数sign的准确性，签名加密参数或方法错误；
解决方案：
1、检查接口地址是否正确，比如沙箱环境和生产环境的地址混淆；
2、检查参数名称和参数值是否按照接口文档规范要求填写；
3、参数值null做为字符串参与签名；
4、按照“签名计算规则说明”文档示例数据在本地进行加密，比对加密结果排查问题；
5、接口请求签名、接口响应签名、异步回调签名规则都是一样；
1017必须传入请求参数集合错误原因：
接口请求时biz_content参数不能为空，必须传入biz_content请求参数；
解决方案：
1、在请求接口中填入biz_content参数，如果没有业务参数，biz_conent的值为"{}"；
1018缺少必要参数错误原因：
接口请求时缺少必要参数，接口中缺失必填字段参数；
解决方案：
1、在开放平台在线调试获取模拟请求参数，进行参数比对；
1019访问IP不在IP白名单内错误原因：
接口请求服务器的外网IPv4格式IP地址没有添加到商户控制台->应用管理->参数配置->IP白名单配置；
解决方案：
请将接口响应信息中的IP地址添加进去（目前各接口没有校验IP白名单，可不必配置IP白名单）。
5001系统异常错误原因：
1、请求参数(值或类型)与文档不匹配；
2、系统内部异常；
解决方案：
1、开发环境：
①请求接口方式：仅支持HTTP POST请求，Content-Type必须设置为：application/json；
②biz_content参数值需要正常解析为json的字符串类型，而非对象；
③在开放平台在线调试获取模拟请求参数进行参数比对；
2、生产环境：
1、下单接口，订单下单失败，因系统异常未下单成功，订单可按失败处理；
2、其他接口，排查掉问题后，重新发起请求；

业务返回码#

商品API#

获取商品列表接口返回码#
返回码返回码描述解决方案
2003商户或应用配置异常错误原因：
商户控制台->应用管理->密钥管理中的配置信息异常，导致在各接口中没有找到商户编号信息；
解决方案：
1、接口请求时没有获取到充值API应用配置的应用编号信息，请联系运营处理；
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；
获取商品信息接口返回码#
返回码返回码描述解决方案
3000必须传入商品编号错误原因：
获得商品信息接口请求时商品编号product_id参数不能为空，必须传入商品编号请求参数；
解决方案：
1、在请求接口中填入商品编号product_id参数；
3001商品不存在或无法购买错误原因：
1、沙箱环境，只能使用沙箱环境测试数据；
2、测试环境商品数据不能用于正式环境；
3、正式环境运营未配置商品信息；
4、用户存在多个商户号，请求的商户号没有配置商品；
解决方案：
1、检查接口地址是否正确，比如测试环境和生产环境的地址混淆；
2、沙箱环境使用测试环境相关数据；
3、正式环境商品信息需要联系运营获取；
3002商品已下架错误原因：
接口下单时商品为下架状态；
解决方案：
1、请联系运营检查生产环境商品配置；
3003商品维护中错误原因：
接口下单时商品为维护中状态；
解决方案：
1、请联系运营检查生产环境商品配置；
3004商品在维护期内错误原因：
接口下单时商品为维护期内状态；
解决方案：
1、请联系运营处理；
3005商品库存不足错误原因：
接口请求时校验库存不足；
解决方案：
1、请联系运营检查生产环境商品库存情况，如有活动需要大数量商品请向运营提前报备；
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；
获取商品模板接口返回码#
返回码返回码描述解决方案
2003商户或应用配置异常错误原因：
商户控制台->应用管理->密钥管理中的配置信息异常，导致在各接口中没有找到商户编号信息；
解决方案：
1、接口请求时没有获取到充值API应用配置的应用编号信息，请联系运营处理；
3006必须传入商品模板编号错误原因：
接口请求时商品模板编号template_id不能为空，必须传入template_id请求参数；
解决方案：
1、在请求接口中填入商品模板编号template_id；
3007商品模板不存在错误原因：
获取商品模板接口请求时，根据“模板id”找不到模板信息；
解决方案：
1、检查商品模板id是否传递错误；
2、请联系运营检查生产环境商品配置；
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；
商品库存校验接口返回码#
返回码返回码描述解决方案
2003商户或应用配置异常错误原因：
商户控制台->应用管理->密钥管理中的配置信息异常，导致在各接口中没有找到商户编号信息；
解决方案：
1、接口请求时没有获取到充值API应用配置的应用编号信息，请联系运营处理；
3000必须传入商品编号错误原因：
获得商品信息接口请求时商品编号product_id参数不能为空，必须传入商品编号请求参数；
解决方案：
1、在请求接口中填入商品编号product_id参数；
3009商品异常，商品库存状态无法查询错误原因：
1、沙箱环境，只能使用沙箱环境测试数据；
2、测试环境商品数据不能用于正式环境；
3、商品信息不存在；
解决方案：
1、检查接口地址是否正确，比如测试环境和生产环境的地址混淆；
2、沙箱环境使用测试环境相关数据；
3、正式环境商品信息需要联系运营获取确认；
4001购买数量必须大于0错误原因：
直充下单接口或卡密下单接口请求时buy_num参数不能小于等于零；
解决方案：
1、修改请求接口中填入buy_num参数大于零；
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；

订单API#

直充下单接口返回码#
返回码返回码描述解决方案
2002无效的商户或应用错误原因：
接口请求时校验商户信息，但该商户的审核状态或认证状态不正常；
解决方案：
1、下单接口中，可能存在该商户不存在、商户未认证、商户未审核、商户应用被禁用这几种情况，请联系运营处理；
2003商户或应用配置异常错误原因：
商户控制台->应用管理->密钥管理中的配置信息异常，导致在各接口中没有找到商户编号信息；
解决方案：
1、接口请求时没有获取到充值API应用配置的应用编号信息，请联系运营处理；
2004商户余额不足错误原因：
接口下单时商户余额不足；
解决方案：
1、请联系运营处理；
3000必须传入商品编号错误原因：
获得商品信息接口请求时商品编号product_id参数不能为空，必须传入商品编号请求参数；
解决方案：
1、在请求接口中填入商品编号product_id参数；
3001商品不存在或无法购买错误原因：
1、沙箱环境，只能使用沙箱环境测试数据；
2、测试环境商品数据不能用于正式环境；
3、正式环境运营未配置商品信息；
4、用户存在多个商户号，请求的商户号没有配置商品；
解决方案：
1、检查接口地址是否正确，比如测试环境和生产环境的地址混淆；
2、沙箱环境使用测试环境相关数据；
3、正式环境商品信息需要联系运营获取；
3002商品已下架错误原因：
接口下单时商品为下架状态；
解决方案：
1、请联系运营检查生产环境商品配置；
3003商品维护中错误原因：
接口下单时商品为维护中状态；
解决方案：
1、请联系运营检查生产环境商品配置；
3004商品在维护期内错误原因：
接口下单时商品为维护期内状态；
解决方案：
1、请联系运营处理；
3005商品库存不足错误原因：
接口请求时校验库存不足；
解决方案：
1、请联系运营检查生产环境商品库存情况，如有活动需要大数量商品请向运营提前报备；
3008商品类型错误错误原因：
下单时直充商品使用了卡密下单接口，或卡密商品使用了直充接口；
解决方案：
1、使用与商品类型对应的接口下单；
4000必须传入外部订单号错误原因：
下单或查单接口请求时customer_order_no参数不能为空，必须传入外部订单号参数；
解决方案：
1、在请求接口中填入customer_order_no参数；
4001购买数量必须大于0错误原因：
直充下单接口或卡密下单接口请求时buy_num参数不能小于等于零；
解决方案：
1、修改请求接口中填入buy_num参数大于零；
4002必须传入充值账号错误原因：
非卡密下单接口请求时充值账号charge_account参数不能为空；
解决方案：
1、在请求接口中填入充值账号charge_account参数；
4004充值账号在黑名单中错误原因：
非卡密下单接口请求时充值账号在黑名单中；
解决方案：
1、请联系运营处理；
4008添加订单失败错误原因：
下单接口请求时，下单发生异常；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed为止。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
4009执行下单超时，请查单确认下单结果错误原因：
下单接口请求时，下单发生异常；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed为止。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
4010外部订单号已存在错误原因：
接口下单时已正常下单成功，请不要用同样的订单号重复提交订单下单；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed这两个最终状态为止。其他订单状态（比如：untreated、processing）是没有充值结果的状态，请不要按有最终充值结果的业务场景处理。（注意：订单只会保留2个月，2个月之前的订单，如果再下单，则会提交成功）；
2、订单查询接口是必须要对接的接口，请务必实现主动查询的方式来闭环业务，而不是仅仅被动等待订单异步回调通知的方式来得到充值结果（可能因为网络波动等原因，回调有可能发不出去，或回调接口接收不到）。
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；
5000系统异常，订单可疑错误原因：
1、请求查单接口时，请求参数(值或类型)与文档不匹配；
2、请求下单接口时，系统内部异常；
解决方案：
1、测试环境：
联系技术排查处理；
2、生产环境：
联系运营处理。请调用查单接口持续查询订单状态。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
卡密下单接口返回码#
返回码返回码描述解决方案
2000商户不存在错误原因：
接口请求时校验商户信息，但没有找到商户信息；
解决方案：
1、请核对AppKey，或联系运营处理；
2001商户已被禁用错误原因：
接口请求时校验商户信息，但商户的状态是禁用的；
解决方案：
1、请联系运营处理；
2002无效的商户或应用错误原因：
接口请求时校验商户信息，但该商户的审核状态或认证状态不正常；
解决方案：
1、下单接口中，可能存在该商户不存在、商户未认证、商户未审核、商户应用被禁用这几种情况，请联系运营处理；
2003商户或应用配置异常错误原因：
商户控制台->应用管理->密钥管理中的配置信息异常，导致在各接口中没有找到商户编号信息；
解决方案：
1、接口请求时没有获取到充值API应用配置的应用编号信息，请联系运营处理；
2004商户余额不足错误原因：
接口下单时商户余额不足；
解决方案：
1、请联系运营处理；
3000必须传入商品编号错误原因：
获得商品信息接口请求时商品编号product_id参数不能为空，必须传入商品编号请求参数；
解决方案：
1、在请求接口中填入商品编号product_id参数；
3001商品不存在或无法购买错误原因：
1、沙箱环境，只能使用沙箱环境测试数据；
2、测试环境商品数据不能用于正式环境；
3、正式环境运营未配置商品信息；
4、用户存在多个商户号，请求的商户号没有配置商品；
解决方案：
1、检查接口地址是否正确，比如测试环境和生产环境的地址混淆；
2、沙箱环境使用测试环境相关数据；
3、正式环境商品信息需要联系运营获取；
3002商品已下架错误原因：
接口下单时商品为下架状态；
解决方案：
1、请联系运营检查生产环境商品配置；
3003商品维护中错误原因：
接口下单时商品为维护中状态；
解决方案：
1、请联系运营检查生产环境商品配置；
3004商品在维护期内错误原因：
接口下单时商品为维护期内状态；
解决方案：
1、请联系运营处理；
3005商品库存不足错误原因：
接口请求时校验库存不足；
解决方案：
1、请联系运营检查生产环境商品库存情况，如有活动需要大数量商品请向运营提前报备；
3008商品类型错误错误原因：
下单时直充商品使用了卡密下单接口，或卡密商品使用了直充接口；
解决方案：
1、使用与商品类型对应的接口下单；
4000必须传入外部订单号错误原因：
下单或查单接口请求时customer_order_no参数不能为空，必须传入外部订单号参数；
解决方案：
1、在请求接口中填入customer_order_no参数；
4001购买数量必须大于0错误原因：
直充下单接口或卡密下单接口请求时buy_num参数不能小于等于零；
解决方案：
1、修改请求接口中填入buy_num参数大于零；
4008添加订单失败错误原因：
下单接口请求时，下单发生异常；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed为止。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
4009执行下单超时，请查单确认下单结果错误原因：
下单接口请求时，下单发生异常；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed为止。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
4010外部订单号已存在错误原因：
接口下单时已正常下单成功，请不要用同样的订单号重复提交订单下单；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed这两个最终状态为止。其他订单状态（比如：untreated、processing）是没有充值结果的状态，请不要按有最终充值结果的业务场景处理。（注意：订单只会保留2个月，2个月之前的订单，如果再下单，则会提交成功）；
2、订单查询接口是必须要对接的接口，请务必实现主动查询的方式来闭环业务，而不是仅仅被动等待订单异步回调通知的方式来得到充值结果（可能因为网络波动等原因，回调有可能发不出去，或回调接口接收不到）。
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；
5000系统异常，订单可疑错误原因：
1、请求查单接口时，请求参数(值或类型)与文档不匹配；
2、请求下单接口时，系统内部异常；
解决方案：
1、测试环境：
联系技术排查处理；
2、生产环境：
联系运营处理。请调用查单接口持续查询订单状态。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
话费下单接口返回码#
返回码返回码描述解决方案
2002无效的商户或应用错误原因：
接口请求时校验商户信息，但该商户的审核状态或认证状态不正常；
解决方案：
1、下单接口中，可能存在该商户不存在、商户未认证、商户未审核、商户应用被禁用这几种情况，请联系运营处理；
2003商户或应用配置异常错误原因：
商户控制台->应用管理->密钥管理中的配置信息异常，导致在各接口中没有找到商户编号信息；
解决方案：
1、接口请求时没有获取到充值API应用配置的应用编号信息，请联系运营处理；
2004商户余额不足错误原因：
接口下单时商户余额不足；
解决方案：
1、请联系运营处理；
3001商品不存在或无法购买错误原因：
1、沙箱环境，只能使用沙箱环境测试数据；
2、测试环境商品数据不能用于正式环境；
3、正式环境运营未配置商品信息；
4、用户存在多个商户号，请求的商户号没有配置商品；
解决方案：
1、检查接口地址是否正确，比如测试环境和生产环境的地址混淆；
2、沙箱环境使用测试环境相关数据；
3、正式环境商品信息需要联系运营获取；
3002商品已下架错误原因：
接口下单时商品为下架状态；
解决方案：
1、请联系运营检查生产环境商品配置；
3003商品维护中错误原因：
接口下单时商品为维护中状态；
解决方案：
1、请联系运营检查生产环境商品配置；
3004商品在维护期内错误原因：
接口下单时商品为维护期内状态；
解决方案：
1、请联系运营处理；
3005商品库存不足错误原因：
接口请求时校验库存不足；
解决方案：
1、请联系运营检查生产环境商品库存情况，如有活动需要大数量商品请向运营提前报备；
4000必须传入外部订单号错误原因：
下单或查单接口请求时customer_order_no参数不能为空，必须传入外部订单号参数；
解决方案：
1、在请求接口中填入customer_order_no参数；
4002必须传入充值账号错误原因：
非卡密下单接口请求时充值账号charge_account参数不能为空；
解决方案：
1、在请求接口中填入充值账号charge_account参数；
4003充值账号不是手机号错误原因：
话费下单接口和流量下单接口请求时，充值账号不是手机号格式；
解决方案：
1、请使用手机号作为充值账号下单；
4004充值账号在黑名单中错误原因：
非卡密下单接口请求时充值账号在黑名单中；
解决方案：
1、请联系运营处理；
4005充值面值(数额)必须大于0错误原因：
话费下单接口和流量下单接口请求时，充值面值(数额)必须大于零；
解决方案：
1、调整充值面值大于零；
4008添加订单失败错误原因：
下单接口请求时，下单发生异常；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed为止。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
4009执行下单超时，请查单确认下单结果错误原因：
下单接口请求时，下单发生异常；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed为止。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
4010外部订单号已存在错误原因：
接口下单时已正常下单成功，请不要用同样的订单号重复提交订单下单；
解决方案：
1、请调用查单接口持续查询订单状态，直到获得order_state=success或failed这两个最终状态为止。其他订单状态（比如：untreated、processing）是没有充值结果的状态，请不要按有最终充值结果的业务场景处理。（注意：订单只会保留2个月，2个月之前的订单，如果再下单，则会提交成功）；
2、订单查询接口是必须要对接的接口，请务必实现主动查询的方式来闭环业务，而不是仅仅被动等待订单异步回调通知的方式来得到充值结果（可能因为网络波动等原因，回调有可能发不出去，或回调接口接收不到）。
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；
5000系统异常，订单可疑错误原因：
1、请求查单接口时，请求参数(值或类型)与文档不匹配；
2、请求下单接口时，系统内部异常；
解决方案：
1、测试环境：
联系技术排查处理；
2、生产环境：
联系运营处理。请调用查单接口持续查询订单状态。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；
注意：不要轻易失败订单，请一定要查单来确认订单状态；请不要使用同样的订单号重复下单，对于下单成功、订单可疑的订单，请通过订单查询接口获得最终充值结果。
订单查询接口返回码#
返回码返回码描述解决方案
2003商户或应用配置异常错误原因：
商户控制台->应用管理->密钥管理中的配置信息异常，导致在各接口中没有找到商户编号信息；
解决方案：
1、接口请求时没有获取到充值API应用配置的应用编号信息，请联系运营处理；
2004商户余额不足错误原因：
接口下单时商户余额不足；
解决方案：
1、请联系运营处理；
4000必须传入外部订单号错误原因：
下单或查单接口请求时customer_order_no参数不能为空，必须传入外部订单号参数；
解决方案：
1、在请求接口中填入customer_order_no参数；
4011订单不存在错误原因：
下单接口或查单接口请求时，传入的外部订单号customer_order_no不存在；
解决方案：
1、请调用查单接口持续查询订单状态。如果查单返回4011(订单不存在)，并且120分钟后，还是返回4011状态，则订单将会自动拦截按失败处理（目前此功能暂只支持可疑订单拦截白名单内的商户做此处理）此时查单接口返回的订单状态为failed。由于订单是可疑自动拦截，没有到平台底层充值，所以最终查单结果和订单异步回调信息中没有平台订单号。另外也可在订单被视为可疑订单后（大概下单40分钟后），联系运营人工处理拦截；（注意：不要轻易失败订单，请一定要查单来确认订单状态。另外订单只会保留2个月，2个月之前的订单，查询时会提示不存在）；
2、订单查询接口是必须要对接的接口，请务必实现主动查询的方式来闭环业务，而不是仅仅被动等待订单异步回调通知的方式来得到充值结果（可能因为网络波动等原因，回调有可能发不出去，或回调接口接收不到）。
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；
订单扩展信息查询接口返回码#
返回码返回码描述解决方案
---

商户API#

获取商户信息接口返回码#
返回码返回码描述解决方案
2000商户不存在错误原因：
接口请求时校验商户信息，但没有找到商户信息；
解决方案：
1、请核对AppKey，或联系运营处理；
2001商户已被禁用错误原因：
接口请求时校验商户信息，但商户的状态是禁用的；
解决方案：
1、请联系运营处理；
2002无效的商户或应用错误原因：
接口请求时校验商户信息，但该商户的审核状态或认证状态不正常；
解决方案：
1、下单接口中，可能存在该商户不存在、商户未认证、商户未审核、商户应用被禁用这几种情况，请联系运营处理；
2003商户或应用配置异常错误原因：
商户控制台->应用管理->密钥管理中的配置信息异常，导致在各接口中没有找到商户编号信息；
解决方案：
1、接口请求时没有获取到充值API应用配置的应用编号信息，请联系运营处理；
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；

其他API#

对账单申请接口返回码#
返回码返回码描述解决方案
2114必须传入对账单获取单号错误原因：
对账单申请接口请求时”账单获取单号”不能为空，必须传入”账单获取单号”请求参数；
解决方案：
1、在请求接口中填入”账单获取单号”参数(每次获取对账单的获取单号需要唯一，规则同下单接口中的外部订单号。)；
2115必须传入对账单主题错误原因：
对账单申请接口请求时”账单主题”不能为空，必须传入”账单主题”请求参数；
解决方案：
1、在请求接口中填入”账单主题”参数(对账单主题必须是汉字、数字、字母和下划线组成，长度50以内)；
2116对账单主题格式错误错误原因：
对账单申请接口请求时”账单主题”格式不符合要求；
解决方案：
1、在请求接口中按要求填入”账单主题”参数(对账单主题必须是汉字、数字、字母和下划线组成，长度50以内)；
2117必须传入账单类型错误原因：
对账单申请接口请求时”对账单类型”不能为空，必须传入”对账单类型”请求参数；
解决方案：
1、在请求接口中填入”对账单类型”参数(账单类型只能是1 (excel对账)、2(sftp对账))；
2118必须传入账单类型错误原因：
对账单申请接口请求时”对账单类型”格式不符合要求；
解决方案：
1、在请求接口中按要求填入”对账单类型”参数(账单类型只能是1 (excel对账)、2(sftp对账))；
2119对账单excel列头错误错误原因：
对账单申请接口请求时excel_column_header参数不符合规范；
解决方案：
1、在请求接口中按要求填入excel_column_header（生成excel的列头，Code必须是以下值：【OrderId,CustomerOrderNo,ChargeAccount,OrderType,BizType,OrderouterStatus,ProductId,ProductName,InvoiceType,MemberCode,MemberName,FaceValue,Buynum,PayAmount,RefundAmount,Createtime,Finishtime】，Title可以自定义且长度只能是10以内的汉字。列头可以自定义顺序减少列数，但必须与code表示的值相对应）；
2120必须传入开始时间和结束时间错误原因：
对账单申请接口请求时”开始时间和结束时间”不能为空，必须传入”开始时间和结束时间”请求参数；
解决方案：
1、在请求接口中填入”开始时间和结束时间”参数(时间格式为：yyyy-MM-dd，开始时间不能大于结束时间且时间差不能超过1个月)；
2121开始时间或结束时间错误错误原因：
对账单申请接口请求时“开始时间和结束时间”参数不符合规范；
解决方案：
1、在请求接口中填入”开始时间和结束时间”参数(时间格式为：yyyy-MM-dd，开始时间不能大于结束时间且时间差不能超过1个月)；
4012查询异常，请重试错误原因：
请求用户接口、获得商品信息接口、获得商品模板接口、查单接口时，请求参数与文档不匹配；
解决方案：
在开放平台在线调试获取模拟请求参数进行参数比对，自行排查，或联系运营处理；
手机号归属地查询接口返回码#
返回码返回码描述解决方案
4013无法查询归属地,城市编码等信息错误原因：
手机号归属地接口请求时，找不到手机号对应的归属地、城市码等信息；
解决方案：
1、请联系运营处理；
上一页
卡密解密说明
下一页
免责声明
Built with