创客贴-会员直充接入文档V1.pdf

会员直充API接入指南

• 本文档为研发和测试工程师提供会员直充API接入的详细指导，快速了解接口流程、签名算法及使用方法。
• 你能获得：快速集成会员直充功能，简化开发流程，减少对接问题，提升效率。

核心内容：

1. 接入服务流程

• 联系商务或运营人员，获取商户号 (mchNo)、App ID、Key (公私钥) 以及相关商品套餐 code (goodsCode)。
• 名词解释:
  • 商户号 (mchNo): 平台分配给商户的唯一标识。
  • 商品编码 (goodsCode): 每个会员套餐对应的唯一编码。
  • 平台私钥 (Private Key): 用于接口请求时进行签名。
  • 平台公钥 (Public Key): 用于接口接收时进行验签。

2. 接口说明

• API采用REST风格设计，使用HTTP响应代码表示请求结果。
• 所有API请求和响应都使用JSON格式。
  • 响应数据格式:

    {
        "msg": "success",
        "code": 200,
        "date": {}
    }
    

    • code: 返回码，200表示成功，非200表示错误。
    • msg: 返回码描述，错误时返回错误信息。
    • data: 返回数据，错误时返回null。

3. 签名算法

• 开发者需要自行实现签名，用于接口的安全性验证。
  1. 筛选并排序:
     • 获取所有请求参数（不包括字节类型参数，如文件、字节流）。
     • 剔除sign字段和值为空的参数。
     • 按照参数名的ASCII码递增排序。
  2. 拼接:
     • 将排序后的参数与其对应值，组合成 "参数=参数值" 的格式。
     • 使用&字符连接这些参数，生成待签名字符串。例如：

       mchNo=9910006329&version=1.0&nonce=1.0

  3. 签名:
     • 使用SHA256WithRSA (signType为RSA2) 签名函数，利用开发者私钥对待签名字符串进行签名。
     • 将签名结果进行Base64编码。

4. 充值接口

• 用于用户会员充值。
  • URL:

    /vip/channel/v1/recharge

  • Method: POST
  • 需要鉴权: 是
  • 请求参数：

    • mchNo

      (String, 必填): 平台分配的商户号。

    • goodsCode

      (String, 必填): 平台分配的商品编码。

    • tradeNo

      (String, 必填): 交易号，接入方生成，不长于32位，保证唯一性。

    • phoneNumber

      (String, 必填): 充值手机号。

    • version

      (String, 必填): 版本号，固定值1.0。

    • nonce

      (String, 必填): 随机字符串，不长于32位。

    • timestamp

      (Long, 必填): 时间戳 (毫秒)。

    • attach

      (String, 可选): 附加数据，不超过200位。

    • sign

      (String, 必填): 签名。
  • 请求示例：

  {
      "attach": "XX会员直充",
      "goodsCode": "1224",
      "mchNo": "10110530",
      "nonce": "2324234234",
      "phoneNumber": "15612111111",
      "sign": "LFiFEYFSoX1vq4i43orCjz2VljzwFkYGke4FyztzSV8aXRe9R1WWXkKOszsnFOt1okS6D+K4nH8JdhfZLfYLndQDXRVoW+95NZJQY+8/+N8CJwDUfaCoiqcL2kwC83HXahWA2x4HC4BL80P5kJq4f8lkBi1qDtq6CTCjr6V4ztKQFMehJAPmuDNliudwvLWRv+VLMrRx03E3Q/sIBo77xVWxwnVLFmROG6jNQUndlPt+LJ9OH1RoCnC0NTEClXhT988EuiucWGbOXnZFdEixAntuHeSO9OY5ZZE4zRJOzhW1NozHyBXVVcCyu4ksrlaZHVuYVc9U78ps2i5iG0Xrig==",
      "timestamp": 612343253426,
      "tradeNo": "23432534134546",
      "version": "1.0"
  }
  

  • 成功响应：

  {
      "code": 200,
      "data": {
          "serialNo": "32431923243432343255JDcd"
      },
      "msg": "success"
  }
  

   -   `serialNo` (String): 本次交易流水号，具备唯一性，不长于32位。
  

5. 会员退费/取消充值接口

• 用于取消用户的会员充值。
  • URL:

    /vip/channel/v1/cancel

  • Method: POST
  • 需要鉴权: 是
  • 请求参数：

    • mchNo

      (String, 必填): 平台分配的商户号。

    • tradeNo

      (String, 可选): 交易号 (与流水号不能同时为空)。

    • serialNo

      (String, 可选): 流水号 (与交易号不能同时为空)。

    • version

      (String, 必填): 版本号，固定值1.0。

    • timestamp

      (Long, 必填): 时间戳。

    • nonce

      (String, 必填): 随机字符串，不长于32位。

    • sign

      (String, 必填): 签名。
  • 请求示例：

  {
      "mchNo": "10110530",
      "nonce": "2324234234",
      "serialNo": "32431923243432343255JDcd",
      "sign": "X XXXX",
      "timestamp": "1717121037932",
      "tradeNo": "2431923243432343",
      "version": "1.0"
  }
  

  • 成功响应：

  {
      "code": 200,
      "msg": "success",
      "data": null
  }
  

问答

Q: 如何进行接口签名？

A: 签名步骤包括筛选排序参数、拼接成字符串，然后使用SHA256WithRSA算法和私钥对待签名字符串进行签名，并进行Base64编码。

Q:

tradeNo

和

serialNo

在退费接口中有什么区别？

A:

tradeNo

是接入方生成的交易号，

serialNo

是平台返回的流水号。退费时，两者必须提供其一，不能同时为空。

Q: 常见的错误码有哪些？

A:

• 200: 成功
• 10000: 相关参数错误
• 10001: 流水号或交易号查询异常
• 30000: 充值业务异常 (一般用户账号或订单异常，可联系商务运营查看 )
• 30002: 交易号异常 （ 需要保证交易号的唯一性 ， 每次交易都需要新的交易号）
• 30003: 商户号不存在等相关问题，需联系商务运营查看
• 30004: 用户充值额度不足 ，需联系联系商务运营充值
• 30005: 验证签名失败
• 30006: 退费订单异常问题，需联系商务运营查看