钱账通系统接口文档说明

文档目的:

本文档为使用钱账通系统的平台及商户开发者编写

本文档为钱账通的开发者和相关人员提供有效的指引和帮助

本文档的目标读者为产品及技术人员

接口通讯及对接准备

通讯方式

使用HTTP(S)作为通讯方式,调用方式为POST,报文格式JSON

信息体说明

本系统报文接口数据使用的字符集是UTF-8,在数据传输前各字段数据必须经过URL编码

系统对接前准备

  • 获取应用ID
  • 设置加密证书、签名证书
  • 获取系统接入URL

报文说明

报文中,各字段属性,如果不可空,则必须填写,否则报错;如果空,那么该字段可以在JSON报文中出现,也可以不出现。所有金额以分为单位

接口说明

协议形式
      scheme://hostname/service?parameters
示例
      https://api.xxxxx.com/service/soa

平台使用HTTPS协议作为承载协议 POST JSON模式

HTTP请求方式: POST,消息体的承载类型为:
Content-Type:application/json 
编码:UTF-8
示例
{
  "app_id": "应用ID",
  "timestamp": "1725813559",
  "version": "3.0",
  "sign": "xxxx",
  "service": "服务名",
  "params":{
      "key": "value",
      "key": "value",
      "key": [{
           "key": "value",
            .....
          }],
     "key": {
          "key": "value",
          ......
       }
   }
}

平台使用HTTPS协议作为承载协议 普通HTTP POST模式

POST /endpoint HTTP/1.1
Host: api.xxxxx.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 29
"app_id"="10001"
"timestamp"="1450654868"
"version"="1.0"
"sign"="签名"
"service"="member.create"
"params"={
    "name":"value"
}

服务地址
      https://api.xxxxx.com/service/soa

请求数据

参数名称 参数说明 参数类型 备注 是否必选
app_id 平台分配的应用ID String(32) 必选
timestamp UNIX时间戳 String(32) 请求时间与标准时间的误差不能超过10分钟 必选
version API版本 String(8) 目前版本为3.0 必选
sign 签名 String(512) 参考签名机制 必选
service 请求的服务名称 String(64) 必选
params 请求参数 String(2048) JSON格式的参数对,例如:
{
   “name1” : value1
      “name2” : value2
      …
}
可选

返回数据

返回数据采用JSON格式,例如:
{
      “sign” : “签名”,
      “response” : “…”
}
参数说明

参数名称 参数说明 备注 是否必选
sign 签名 对response值的签名结果 必选
response 字符串格式的返回内容 response的值是字符串形式的,经过对response值的再次JSON解析可以获取服务的实际返回值 必选

response的值再次经过JSON解析后的返回内容

参数名称 参数说明 备注 是否必选
status 服务状态 ”OK”表示成功;”ERROR”表示失败 必选
result 服务的返回对象 必选
error_code 当请求失败时返回的错误代码,仅当status=error时有效 可选
message 当请求失败时返回的错误信息,仅当status=error时有效 可选

签名机制

每一个对接的应用都会从平台获取一对签名密钥,通过这对密钥完成与平台交互时的签名和验证的过程。
签名算法:DSA
签名密钥:私钥。私钥从证书文件中获取
验证密钥:公钥。公钥从证书文件中获取

  • 服务请求的签名内容
    app_id,timestamp,version,service,params参数值的字符拼接:
    app_id + timestamp + version + service + params
    注意:必须在生成签名后再对各参数进行URL编码
  • 服务响应的签名内容
    response的字符串值
    注意:必须先对response值做签名验证,再对response的值做JSON解析
文档更新时间: 2024-09-09 15:51   作者:周兴奎