开发指引

更新时间：2024.09.20

访问测试环境

欲访问测试环境，请联系微信支付同学。

错误码

HTTP状态码	错误类型	错误码	原参数重试
200 - OK	处理成功
202 - Accept	请求已受理，后续处理中
204 - No Content	请求处理成功，没有数据返回
400 - Bad Request	参数不符合协议要求	PARAM_ERROR/INVALID_REQUEST	否
401 - Unauthorized	签名验证失败	SIGN_ERROR	否
403 - Forbidden	签名验证通过，但商户业务权限异常，或者业务规则限制导致失败	NO_AUTH/NOT_ENOUGH	否
404 - Not Found	URL不正确或请求的资源不存在	ORDER_NOT_EXISTS	否
406 - Not Acceptable	服务器无法提供与请求匹配的响应
429 - Too Many Requests	请求超过频率限制	RATE_LIMITED	可
500 - Server Error	系统错误	SYSTEM_ERROR	可
502 - Bad Gateway	服务下线，暂时不可用
503 - Service Unavailable	服务不可用，过载保护	SYSTEM_ERROR	可

错误码回报格式：

字段名称	字段类型	是否必需	字段说明
code	string	Y	错误码，如INVALID_REQUEST、PARAM_ERROR等上述HTTP状态码中对应的错误码
message	string	Y	错误消息，如”参数错误“

其他规范：

支付侧接口字段均采用下划线命名法
支付侧时间字段采用rfc3339规范中date-time格式，如2022-09-26T10:57:10+08:00，或者，日期使用rfc3339规范中full-date格式，如2022-09-26
支付侧金额单位均为分
支付侧接口均通过HTTP状态码确定接口调用结果
支付侧的接口字段为非必传属性时，如果请求没有传入该字段，支付侧就不会校验字段合法性，但如果传入该字段则会进行字段合法性校验（例如：字段为字符串类型时，字段传入""，支付侧会会校验字段长度，如不符合预期则会报错）

接口规范

HTTP格式满足以下要求：

签名信息放在HTTP头Authorization中
请求应携带User-Agent
请求应携带Accept，理论Accept应为"application/json"
请求应使用JSON传输数据，应携带Content-type，且值为"application/json"
鉴权信息放置在HTTP头的Authorization 中，具体格式和内容见下文详细描述。

签名规则

由于养老金主体为微保，无法使用微信支付商户的那一套鉴权机制。本次采用与微信支付类似的鉴权模式，独立实现一套新的鉴权机制。

签名串的规则和HTTP的鉴权字段类似微信支付商户APIv3。

签名和验签的流程如下：

请求的签名

构造签名串

签名串由以下5行组成：

1HTTP请求方法\n
2URL\n
3请求时间戳\n
4请求随机串\n
5请求报文主体\n

例如，使用POST方式请求URL为：https://api.mch.weixin.qq.com/v3/endowmentins/calc/plus

POST数据为{"number_1":1,"number_2":2}

生成的待签名串：

1POST
2/v3/endowmentins/calc/plus
31661776967
45f270f2ff52b0c67dd47cd5c3ee17e91
5{"number_1":1,"number_2":2}

使用SM3计算消息摘要

接上面的例子，对签名串计算SM3消息摘要并以大写的十六进制表示：

15250133FBBB815782E1D8D9D5CAB199BD11ED57E16ADC013FB9AB651B67298E5

计算SM2签名

使用SM2签名算法对上述消息摘要计算签名，并以Base64编码，如下：

1MEUCIE05M8Nm1/g5x49q3h1jo1ShWJjfQW6s1+uI8OkLd8MtAiEAq3fHe8sCOgsXFuMefHUVvzxrJJ49jSg6THlrs4PhkyA=

SM2签名算法参数如下：

签名ID为"1234567812345678"
签名模式为：SM2SignMode_RS_ASN1

生成Authorization

HTTP请求头Authorization由以下字段组成：

version：微保sm2密钥版本号
company_id：支付给微保分配的ID
nonce_str：随机串
timestamp：时间戳
signature：签名

按上述例子，Authorization如下：

1version="1.1.0",company_id="8452619775",nonce_str="5f270f2ff52b0c67dd47cd5c3ee17e91",timestamp="1661776967",signature="MEUCIE05M8Nm1/g5x49q3h1jo1ShWJjfQW6s1+uI8OkLd8MtAiEAq3fHe8sCOgsXFuMefHUVvzxrJJ49jSg6THlrs4PhkyA="

HTTP请求示例如下：

1curl --location --request POST 'https://api.mch.weixin.qq.com/v3/endowmentins/calc/plus' \
2--header 'Authorization: version="1.1.0",company_id="8452619775",nonce_str="5f270f2ff52b0c67dd47cd5c3ee17e91",timestamp="1661776967",signature="MEUCIE05M8Nm1/g5x49q3h1jo1ShWJjfQW6s1+uI8OkLd8MtAiEAq3fHe8sCOgsXFuMefHUVvzxrJJ49jSg6THlrs4PhkyA="' \
3--header 'Content-Type: application/json' \
4--data-raw '{
5    "number_1": 1,
6    "number_2": 2
7}'

响应的签名

HTTP格式

支付侧对回包进行签名，相关字段放在HTTP头中

WxIns-Nonce：随机串
WxIns-Signature：签名
WxIns-Timestamp：时间戳
WxIns-Version：支付sm2密钥版本号

构造响应签名串

1响应时间戳\n
2请求随机串\n
3请求报文主体\n

例如：

11661777028
25d74cabc0fb63621a7dcba2a74b38143
3{"result":3}

计算SM3消息摘要

对签名串计算SM3消息摘要并以大写十六进制表示：

17535E9A06D8CFB6A94638552567EB9441CD75DCE96CB94986653A81B6BE0C4B4

计算响应SM2签名

对上述消息摘要计算SM2签名，并以Base64编码：

1MEUCIQC2Ndc6SrMSrp9rbCoonTqRSvBVWVCeZhVwLEi7JOXIxAIgNYw4sQapgP1g2aR+SU0C8fMsu/6B+KGsbBnlXJ4iyRg=

设置HTTP响应头

1WxIns-Nonce: 5d74cabc0fb63621a7dcba2a74b38143
2WxIns-Signature:      MEUCIQC2Ndc6SrMSrp9rbCoonTqRSvBVWVCeZhVwLEi7JOXIxAIgNYw4sQapgP1g2aR+SU0C8fMsu/6B+KGsbBnlXJ4iyRg=
3WxIns-Timestamp: 1661777028
4WxIns-Version: 1.2.0

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服