jufengpay.github.io

巨锋接口文档(v.200330)

文档内容最后更新于：2020-03-30

特别注意：

  1. 时间戳为秒级，非毫秒级，毫秒级请/1000
  2. returnUrl/notifyUrl 为完整地址,含有协议+端口。如果回调通知地址（notifyUrl）不传，平台不会发起异步回调，需要调用查询接口确认订单状态。
  3. 金额为整数，非小数，以分为单位，不能包含有“·”号，例：123 即 1.23 元。
  4. 商户编号需要从商户后台首页获取，并非登陆账号，商户密钥（apikey）每次刷新都会重新随机生成，保存好最后一次刷新的密钥进行对接即可。
  5. 商户接收异步通知时，不要写死固定参数接收，请使用通用的json/map 对象接收，这样可接收完整参数，然后对json/map 里面的参数进行签名校验。如果只接收固定参数，会导致签名验证失败。后期如果通知增加参数，也可以不用修改代码
  6. 商户测试时如果要确认能不能回调以及验证签名是否成功，可生成订单后直接取消，取消后系统便会有通知。测试完取消通过后，再联系客服测试成功订单

更新记录

  1. 2020.04.13
    1. 新增银行卡api下发接口参数-备注
  2. 2020.03.23
    1. 新增下发查询接口
  3. 2020.03.20
    1. 新增银行卡api下发接口
    2. 修改部分描述
  4. 2019.12.20
    1. 订单状态新增 -20（暂无渠道） ，该状态下无支付信息（支付状态，支付成功时间，支付编号为空）

接口规范

  1. 字符编码：UTF-8
  2. Content-Type：application/json
  3. URL 传输参数需要对参数进行 UrlEncode

接口调用所需条件

  1. 网关地址：请联系客服
  2. 商户编号(merchantNo)
  3. 商户密钥(apiKey)

签名（sign）算法

BCrypt(Base64(SHA-256(apiKey+originalStr+apiKey)))
  1. originalStr: 除sign参数外其他参数值非空（空值或者空字符串）的参数按参数名称字母正序排序然后以name=UrlEncode(value)形式组合， 通过&拼接不同参数。
    1. 注：空值（空值或者空字符串）不参与签名。
    2. 注：value需要进行UrlEncode编码
  2. BCrypt(Base64(SHA-256(apiKey+originalStr+apiKey)))
    1. 用SHA-256算法将“apiKey+originalStr+apiKey”进行签名得到签名信息（二进制,有些工具会生成16进制）
    2. 使用Base64编码对SHA-256二进制签名信息进行编码
    3. 使用BCrypt对编码字符串进行签名得到最终签名字符串
  3. php demo
  4. java demo
  5. c# demo

同步通知 （returnUrl）

当创建订单时传入返回地址，订单结束后，用户点击“返回商户”，会在返回链接带上参数（returnUrl?urlparams）。参数内容参考统一返回参数，可通过签名算法计算签名的正确性。例：

returnUrl?
    amount=100&
    payMode=100001&
    ts=1575948756&
    orderStatus=50&
    payNo=20191209194326631108714792&
    payStatus=30&
    payTime=1575948756&
    merchantNo=20191204192421307122140114&
    orderNo=201912081855183951ab02e&
    sign=%242a%2410%24JwOX9nmVHrE6o8vcoSmyd.T69Yl7n322tVLmz.pVkRUz%2f.tRCjELS

异步回调 （notifyUrl）

当创建订单时传入异步回调地址时，订单结束后（用户取消订单(-30)、用户支付超时（-40）、订单失败（-50）、订单已完成（50））进行通知，总共通知3次，间格时间分别为0s,15,60s，超时时间为10s，处理成功后返回 success，返回其他字符表示处理失败，会继续进行后续通知。通知内容参考统一返回参数，可通过签名算法计算签名的正确性 示例：

curl -X POST "回调地址"
  -H 'content-type: application/json' 
  -d '{
    "amount":100,
    "payMode":"100001",
    "ts":1575948756,
    "orderStatus":50,
    "payNo":"20191209194326631108714792",
    "payStatus":30,
    "payTime":1575948756,
    "merchantNo":"20191204192421307122140114",
    "orderNo":"201912081855183951ab02e",
    "sign":"$2a$10$JwOX9nmVHrE6o8vcoSmyd.T69Yl7n322tVLmz.pVkRUz/.tRCjELS"
}'

1. 订单接口内容

  1. 创建订单接口
    1. 使用场景：当用户充值时，根据下面参数，商户生成跳转链接，返回给用户进行跳转到支付页面。
    2. 请求方式：页面跳转
    3. 请求地址：网关地址+/pay-order/#/?urlparams

    4. 请求参数

      参数名称 必须 数据类型 示例 参数说明
      amount 是 整数 100 金额,以分为单位；最小值100，即1元
      merchantNo 是 字符串 20191204192421307122140114 商户编号
      orderNo 是 字符串(<50) 201912081855183951ab02e 商户订单编号
      payMode 是 字符串 100001 支付模式，请登陆商户后台获取
      ts 是 整数 1575948756 商户订单时间戳（秒级）
      notifyUrl 否 字符串 https://www.baidu.com/notify 后台通知地址
      returnUrl 否 字符串 https://www.baidu.com 支付完成用户返回地址
      sign 是 字符串 $2a$10$JwOX9nmVHrE6o8vcoSmyd.T6… 参数签名，请按照签名算法生成
    5. 响应
    6. 示例 
       网关地址+/pay-order/#/?amount=100&merchantNo=20191204192421307122140114&orderNo=1575730270288&payMode=100001&ts=1575730270&sign=%242a%2410%24JwOX9nmVHrE6o8vcoSmyd.T69Yl7n322tVLmz.pVkRUz%2F.tRCjELS
  2. 查询订单接口
    1. 使用场景：当商户需要对特定订单查询时
    2. 请求方式：POST
    3. 请求地址：网关地址+ /any-pay/open/order/query

    4. 请求参数

      参数名称 必须 数据类型 示例 参数说明
      merchantNo 是 字符串 20191204192421307122140114 商户编号
      orderNo 是 字符串(<50) 201912081855183951ab02e 商户订单编号
      ts 是 整数 1575948756 商户订单时间戳（秒级）
      sign 是 字符串 $2a$10$JwOX9nmVHrE6o8vcoSmyd.T6… 参数签名，请按照签名算法生成
    5. 响应（参考统一返回参数）
    6. 示例 
       请求： curl -X POST "网关地址+/any-pay/open/order/query"  -H  "accept:*/*"  -H  "Content-Type:application/json" -d "{\"merchantNo\":\"20191204192421307122140114\",\"orderNo\":\"201912081855183951ab02e\",\"sign\":\"$2a$10$JwOX9nmVHrE6o8vcoSmyd.T69Yl7n322tVLmz.pVkRUz/.tRCjELS\",\"ts\":1575948756}"
 响应：

统一返回参数

  1. 参数内容

    参数名称 必须 数据类型 示例 参数说明
    amount 是 整数 100 金额,以分为单位
    merchantNo 是 字符串 20191204192421307122140114 商户编号
    orderNo 是 字符串(<50) 201912081855183951ab02e 商户订单编号
    payMode 是 字符串 100001 支付模式
    ts 是 整数 1575948756 商户订单时间戳（秒级）
    orderStatus 是 整数 50 订单状态，请参考订单状态枚举
    payNo 否 字符串 20191209194326631108714792 支付订单编号
    payStatus 否 整数 30 支付状态，请参考支付状态枚举
    payTime 否 整数 1575948756 支付成功时间（秒级）
    sign 是 字符串 $2a$10$JwOX9nmVHrE6o8vcoSmyd.T6… 参数签名，使用BCrypt校验方法校验

  2. 订单状态（orderStatus）枚举

    值 说明
    -20 暂无渠道，此状态下无支付状态
    30 支付等待中
    -30 用户取消订单
    -40 用户支付超时
    -50 订单失败
    50 订单已完成

  3. 支付状态（payStatus）枚举

    值 说明
    10 等待支付
    -10 支付超时
    -20 支付取消
    30 支付成功
    -30 支付失败

以订单状态为主进行判断，支付超时后状态可能会收到支付成功状态通知，请注意处理

2. 下发api接口

  1. 银行卡下发
    1. 使用场景：商户银行卡下发
    2. 请求方式：POST
    3. 请求地址：网关地址+ /any-pay/open/merchant/withdraw-apply
    4. 请求头： X-REQUEST-TOKEN:随机字符串

    5. 请求参数

      参数名称 必须 数据类型 示例 参数说明
      merchantNo 是 字符串 20191204192421307122140114 商户编号
      bankName 是 字符串 中国银行 银行名称
      bankcard 是 字符串 6225804598346543 银行卡号
      realName 是 字符串 张三 持卡人
      passwd 是 字符串 MD5(密码) 提现密码（需要md5）
      amt 是 整数(500000-5000000) 500000 金额（分）
      ts 是 整数 1575948756 商户订单时间戳（秒级）
      remark 否 字符串(<100) 无 备注
      sign 是 字符串 $2a$10$JwOX9nmVHrE6o8vcoSmyd.T6… 参数签名，请按照签名算法生成
    6. 响应:参考响应内容
    7. 示例 
       请求： curl -X POST "网关+/any-pay/open/merchant/withdraw-apply" -H "X-REQUEST-TOKEN:111111we2324" 
 -H "Content-Type:application/json" 
 -d "{\"amt\":500000,\"bankName\":\"中国银行\",\"bankcard\":\"6225804598346543\",\"merchantNo\":\"20191204192421307122140114\",\"passwd\":\"MD5(密码)\",\"realName\":\"张三\",\"sign\":\"$2a$10$JwOX9nmVHrE6o8vcoSmyd.T6\",\"ts\":1575948756}"
  2. 下发查询
    1. 使用场景：商户银行卡下发查询
    2. 请求方式：POST
    3. 请求地址：网关地址+ /any-pay/open/merchant/withdraw-apply/query
    4. 请求头： X-REQUEST-TOKEN:随机字符串

    5. 请求参数

      参数名称 必须 数据类型 示例 参数说明
      merchantNo 是 字符串 20191204192421307122140114 商户编号
      applyNo 是 字符串 201912041924213071221490224 申请编号
      ts 是 整数 1575948756 商户订单时间戳（秒级）
      sign 是 字符串 $2a$10$JwOX9nmVHrE6o8vcoSmyd.T6… 参数签名，请按照签名算法生成
    6. 响应: 参考响应内容
    7. 示例 
       请求： curl -X POST "网关+/any-pay/open/merchant/withdraw-apply/query" 
 -H "X-REQUEST-TOKEN:111111we2324" 
 -H "Content-Type:application/json" 
 -d "{\"merchantNo\":\"20191204192421307122140114\",\"applyNo\":\"201912041924213071221490224\",\"sign\":\"$2a$10$JwOX9nmVHrE6o8vcoSmyd.T6\",\"ts\":1575948756}"

响应内容

  1. 响应参数

    参数名称 必须 数据类型 示例 参数说明
    type 是 字符串 WITHDRAW 类型
    applyNo 是 字符串 201912041924213071221490224 申请编号
    amt 是 整数 500000 金额（分）
    serviceCharge 是 整数 300 服务费金额（分）
    applyStatus 是 整数 10 申请状态
    remark 否 字符串(<100) 无 备注
  2. 枚举值
    1. 申请状态（applyStatus）枚举
    值 说明
    10 等待处理
    13 支付中
    16 待确认
    20 成功
    -20 失败
  3. 示例 
     {"applyNo":"20200323111021811157255464","type":"WITHDRAW","amt":500000,"serviceCharge":300,"applyStatus":20}