报文说明

更新时间：2025.03.06

2.1、通讯模式

生活缴费平台与渠道平台使用 HTTPS 协议进行通讯，提交方式为 POST。接口参数在 HTTPS 包体中采用 XML 方式传递。

2.2、报文编码

报文中可能有汉字，需要对报文进行编码才能正常显示。在调用渠道机构接口时，微信侧采用 UTF-8 编码生成 XML 报文和签名。

2.3、报文格式（非国密）

微信与渠道进行通信时，需对数据进行签名验证。数据通信格式如下：

签名+xml 数据报，其中签名加密方式为 SHA1 或 SHA256，SHA1方式加密串字母为大写,SHA256方式加密串字母为小写

目前系统支持 SHA1 和 SHA256 两种签名方式，优先推荐使用 SHA256。如有特殊情况必须指定其他签名算法，接入时请提前说明。

沙箱环境的HTTP头部字段

HTTP头	必填	说明
LivingPayment-IsSandbox	否	是否是沙箱环境（不参与验签）1：使用沙箱环境 0：使用正式环境，注意本字段填值要和header里保持一致，如果不传默认为正式环境，注意需和head里保持一致，不填或者0表示正式环境

报文范例

请求：

1670B2FA77740D3EA35DB20AAEC42D88FEDDAD20F<?xml version="1.0" encoding="UTF-8"?>
2<wxlifepay>
3    <head>
4        <version>1.0.1</version>
5        <trancode>query</trancode>
6        <transeqnum>305912304</transeqnum>
7        <merchantid>1269692401</merchantid>
8    </head>
9    <info>
10        <bill_key>007226</bill_key>
11        <company_id>595100101</company_id>
12        <begin_num>1</begin_num>
13        <query_num>1</query_num>
14    </info>
15</wxlifepay>
16

18EC63FDB7EA0484E457E25E41FB667BE028CDC53<?xml version="1.0" encoding="UTF-8"?>
2<wxlifepay>
3    <head>
4        <version>1.0.1</version>
5        <trancode>query</trancode>
6        <transeqnum>305912304</transeqnum>
7        <merchantid>1269692401</merchantid>
8        <ret_code>0</ret_code>
9        <err_msg>操作成功</err_msg>
10    </head>
11    <info>
12        <bill_key>007226</bill_key>
13        <company_id>595100101</company_id>
14        <total_num>1</total_num>
15        <data>
16            <customer_name>文榜</customer_name>
17            <balance>0</balance>
18            <pay_amount>0</pay_amount>
19            <begin_date></begin_date>
20            <end_date></end_date>
21            <attach>8a7ba6b65412a9da0154141246b100d3</attach>
22        </data>
23    </info>
24</wxlifepay>
25

字段说明：

报文起始字符为签名字段，签名串为大写字母。

1以SHA1签名方式举例：
2Str1 = Sha1（xml数据包+密钥），密钥拼接在xml数据包后面参与签名
3签名串= toupper(Str1)，转换为大写字符。
4通信数据报：签名串+xml数据包。可参考上述报文范例。
5
6签名示例
7Xml数据包：
8<?xml version="1.0" encoding="UTF-8"?>
9<wxlifepay>
10    <head>
11        <version>1.0.1</version>
12        <trancode>query</trancode>
13        <transeqnum>305912304</transeqnum>
14        <merchantid>1269692401</merchantid>
15        <is_sandbox>1</is_sandbox>
16    </head>
17    <info>
18        <bill_key>007226</bill_key>
19        <company_id>595100101</company_id>
20        <begin_num>1</begin_num>
21        <query_num>1</query_num>
22    </info>
23</wxlifepay>
24
25密钥：abcdefghj123456xyz
26Sha1签名之后签名（字母转化为大写）：EFA8530B85CBDB4399F128419C4A5F11A89D3AFE
27通信数据包：
28EFA8530B85CBDB4399F128419C4A5F11A89D3AFE<?xml version="1.0" encoding="UTF-8"?>
29<wxlifepay>
30    <head>
31        <version>1.0.1</version>
32        <trancode>query</trancode>
33        <transeqnum>305912304</transeqnum>
34        <merchantid>1269692401</merchantid>
35        <is_sandbox>1</is_sandbox>
36    </head>
37    <info>
38        <bill_key>007226</bill_key>
39        <company_id>595100101</company_id>
40        <begin_num>1</begin_num>
41        <query_num>1</query_num>
42    </info>
43</wxlifepay>
44

head 为报文头节点。
version 为协议版本号，固定填入“1.0.1”。
trancode 为接口类型，具体定义参照交易接口。
transeqnum 终端流水号，由微信产生，用作跟踪每笔交易的请求和应答报文，同一天内该值不重复。
merchantid 渠道商的商户号，由微信产生。
ret_code 为错误码，具体定义参照第四部分错误码列表。
err_msg 为处理返回语，用于用户页面提示。
is_sandbox 标识是否是沙箱环境
info 为报文体节点，根据接口填入对应业务数据。

2.4、报文格式（国密）

应监管合规要求，系统之间的数据传输必须满足完整性和机密性，因此需对原数据报文进行加密传输，同时对数据的完整性进行验证。

完整性、机密性

类似数字信封方式，采用SM4-GCM算法对数据报文进行加密传输，采用SM3WithSM2对明文进行签名验证，满足数据完整性验证和抗抵赖验证

加密涉及字段

以下每个字段作为单独的HTTP头部字段

HTTP头	必填	说明
LivingPayment-TimeStamp	是	取当前系统时间戳，单位：秒
LivingPayment-NonceStr	是	随机字符串，固定长度为32
LivingPayment-SignCertId	是	国密签名证书序列号（主调方）
LivingPayment-EncryptCertId	是	国密加密证书序列号（被调方）
LivingPayment-MchId	是	商户号（从业机构号）
LivingPayment-EncryptKey	是	对称密钥的密文
LivingPayment-EncryptVersion	是	对称密钥版本号，格式v+数字，如v1、v2
LivingPayment-Signature	是	签名值，获取方式参照如下国密签名步骤
LivingPayment-EncryptType	是	国密标识，固定值SM
LivingPayment-EncryptIv	是	对称加密的初始向量，长度为16字节可见字符（如数字和大小写字母组合）
LivingPayment-IsSandbox	否	是否是沙箱环境（不参与验签）1：使用沙箱环境 0：使用正式环境，注意本字段填值要和header里保持一致，如果不传默认为正式环境，注意需和head里保持一致，不填或者0表示正式环境

调用方对数据加密及生成签名步骤

接收方对数据签名验证及数据解密步骤

1、解析接收到的http请求，包括header及body信息

2、用调用方公钥，采用SM3WithSM2对请求对签名进行合法性验证

SM3WithSM2算法说明：
SM2算法的身份ID入参为证书序列号签名结果无需ASN1编码

3、用接收方私钥，采用SM2算法解析出对称密钥密文

SM2加解密算法说明：
加密结果格式: C1C3C2结果无需ASN1编码

4、用对称密钥密文，采用SM4-CBC-PKCS#7算法解密出数据明文

SM4-CBC 对称加解密算法说明：
密钥为128bit数据(可能为不可见字符)，iv通过header传递使用PKCS#7填充标准，将明文填充为16字节的整数倍加密后的数据采用Base64对不可见字符进行编码备注: 解密成功，但头部有部分乱码，请检查iv是否正确；也可使用如下命令进行本地检查key和iv是否正确
openssl enc -sm4-cbc -e -K hex_key -iv hex_iv -pbkdf2 -in plaint.txt -out ciphert.txt -a
openssl enc -sm4-cbc -d -K hex_key -iv hex_iv -pbkdf2 -in ciphert.txt -out plaint.txt -a

参与签名的数据

数据报密文（Body）

系统时间戳（LivingPayment-TimeStamp）

随机字符串（LivingPayment-NonceStr）

国密签名证书序列号（LivingPayment-SignCertId）

国密加密证书序列号（LivingPayment-EncryptCertId）

商户号（从业机构号）（LivingPayment-MchId）

对称密钥的密文（LivingPayment-EncryptKey）

对称密钥版本号（LivingPayment-EncryptVersion）

国密标识（LivingPayment-EncryptType）

对称加密的初始向量（LivingPayment-EncryptIv）

计算签名

按照以下方式拼接签名原串，其中'\n'为换行符：

Body + '\n' + LivingPayment-TimeStamp + '\n' + LivingPayment-NonceStr + '\n' + LivingPayment-SignCertId + '\n' +LivingPayment-EncryptCertId + '\n' +LivingPayment-MchId+'\n'+LivingPayment-EncryptKey+'\n'+LivingPayment-EncryptVersion+'\n'+LivingPayment-EncryptType+'\n'+LivingPayment-EncryptIv+'\n'

对以上签名原串进行SM3WithSM2签名，并对签名结果进行Base64编码得到签名值（LivingPayment-Signature）

将系统时间戳（LivingPayment-TimeStamp）、随机字符串（LivingPayment-NonceStr）、签名值（LivingPayment-Signature），国密签名证书序列号（LivingPayment-SignCertId）、国密加密证书序列号（LivingPayment-EncryptCertId）、商户号（从业机构号）（LivingPayment-MchId）、对称密钥的密文（LivingPayment-EncryptKey）、对称密钥版本号（LivingPayment-EncryptVersion）、国密标识（LivingPayment-EncryptType）、对称加密的初始向量（LivingPayment-EncryptIv）设置进HTTP头部

请求包示例数据（非真实数据）

Body明文内容：

1<?xml version="1.0" encoding="UTF-8"?>
2<wxlifepay>
3    <head>
4        <version>1.0.1</version>
5        <trancode>query</trancode>
6        <transeqnum>305912304</transeqnum>
7        <merchantid>1269692401</merchantid>
8    </head>
9    <info>
10        <bill_key>007226</bill_key>
11        <company_id>595100101</company_id>
12        <begin_num>1</begin_num>
13        <query_num>1</query_num>
14    </info>
15</wxlifepay>
16

Body加密后的密文：

O3QmvXeSJxZEM+vAAIbBS2h+Cur8r4Qy7MPaWboxPfvh8fQilSDOwLgYTeQfXOJ8pF5+/LvwxpvCXTBw/BOMCSFsoN44F4cogGWjOanoS7B02QVkmhfwlCGcyKLi5dDIQ3QESov2vrT3feBUDG1sL0+APmug2TZawSgir4Y+M8VaO4INaFezrzcD7xNQofjxww188bIPHVIcsJAC4pYM7t8q4LY8ty6GdtRLXnMybFKyP+LICqNWASqd7JgQHdEY3onh/XKRVvPRCkgfoESb/+4rQxsERmcLCTZo+pu/zA5ZM8yciBuplS+y5kyJpXzVG0T/eQoQpDEMAgPNNjTB6LB7YM+nAyts4cXSab3vCetme3Zp2HAwLHRI397RT7MX0AsV2G0qHRekWWZuyQUCg2kwI/AE7SM0o6xwdMNKi8UAnyULHb2s44CW5pLc3ug/9lWqgtPk3cLmA8g2pNWe4RUW8d/e2mUdVXO1JOdow14xlibdfGSLlwiwngIUQDiT+nqatfAE5s+ywyTzT0t6UPSgyYeHoEpIZeY6+KxtdSk=

HTTP头内容：

LivingPayment-TimeStamp : 1564665325

LivingPayment-NonceStr : 5e680dac294cb6473cd2149bbbb48d71

LivingPayment-Signature ：uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==

LivingPayment-SignCertId : 1234

LivingPayment-EncryptCertId : 5678

LivingPayment-MchId : 14801921092

LivingPayment-EncryptKey : rExwVkI1XO5jCNKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==

LivingPayment-EncryptVersion : v1

LivingPayment-EncryptType : SM

LivingPayment-EncryptIv : 1234567890abcdef

特别说明：

1、每个接口的应答报文也需要生成签名，方便调用者对请求的应答进行合法性验证

2、对称密钥128bit随机生成，基于性能考虑生活缴费发起的请求一段时间范围内保持不变，每次变化都会通过LivingPayment-EncryptVersion版本号字段告知。渠道方用自己的私钥对对称密钥解密后，可以依据情况对对称密钥进行缓存（解密比较消耗cpu资源），当检测到密钥版本发生变化时(或者SM4解密失败时)，再对称密码进行解密。同理，渠道商接口也应采用相同的方式。

注意
渠道方对称密钥发生变化时，请务必更新版本号，否则会导致短时间的通信失败；生活缴费端目前只通过版本号识别密钥是否发生变化，SM4解密失败后并不会兜底解密对称密钥，缓存有效时间为3min，理论上3分钟内的通信会全部失败。由于SM2非对称加密每次加密的密文会不同，所以请不要通过密文内容来识别对称密钥是否发生变化，生活缴费这边多个服务独立缓存密钥密文，所以请求中密文数据会频繁变动。

3、生活缴费请求渠道接口，用生活缴费的平台证书进行签名，公钥给到渠道，渠道用生活缴费平台公钥进行签名验证；渠道请求生活缴费接口，用渠道私钥进行签名，公钥给到生活缴费，生活缴费用公钥进行签名验证

4、加密证书及签名证书

加密证书：用作加密，由被调方提供，在对称密钥加密时使用

签名证书：用作签名，私钥签名，提供公钥给被调方进行签名验证

备注：支持加密证书和签名证书使用不同的证书，商户有相关需求请邮件中备注说明；如无特殊需求，加密、签名建议可以使用一套国密证书，更方便管理。

5、证书获取

测试环境：联系对接的生活缴费运营，可以提供一套测试证书+私钥，以及生活缴费的测试平台证书；也可自行准备测试证书，以邮件方式发送给生活缴费。
生产环境：商户可前往微信支付商户平台，申请并下载国密证书，然后将证书以邮件的方式发送给生活缴费（仅需要证书文件，私钥请自行妥善保管），并注明证书的cert_id以及用途(签名/加密/签名&加密)，验证无误后，我们会邮件回复生活缴费平台方的证书文件；商户亦可自行在信任的证书颁发机构下申请国密证书。

返回包示例数据（非真实数据）

Body明文内容：

1<?xml version="1.0" encoding="UTF-8"?>
2<wxlifepay>
3    <head>
4        <version>1.0.1</version>
5        <trancode>query</trancode>
6        <transeqnum>10000001</transeqnum>
7        <merchantid>1234567</merchantid>
8        <ret_code>0</ret_code>
9        <err_msg>success</err_msg>
10    </head>
11    <info>
12        <bill_key>12345678</bill_key>
13        <company_id>12345</company_id>
14    </info>
15</wxlifepay>
16

Body加密后的密文：

jY4L8jEyrh8FIOOvxjH6prtuaGEOEflDhWGk4PyOHYfLPq5ASWrStQD3hgTIIiXjb+Vt10wsEjvqSq4nBzg18L8y8s0Uxm5QluZQjYkUJBlCyqp5iYCEGjNKu4UIWom5vc18bxKp6EjVgzMXGwQFdV9DKlsdS8SKtz7vd1OUocppOSHRrchMfY1AJQzMJFEQ5bKXw7CbkMoY/K4NQxBBrgcM8H46nUJ2IqRgpep8tWo7xg0OVHx6nzgvMX44Se3lJfJOhmEkEY4yCAQuxK/nrmGxmQJ80f9SLYNHwy8+pUNoFROmaq76Q/rIGtE33ZSDpXcAGfrxyDUdBU7R42VLSDiMYeeRbDOVBBxLjYn3T4Rl8khuC6+1pe/57wRwueqKkg1rbjrQhbsdN8Ra7bxnoz7PuoRtIFVo8Rc2jNFUFrzwxSvq0GPRyhrx3eNLCO/h2nOuoHzXH3OWuEm6fCU/cxof2iQW8s6NqnuqABieOS2q1Rdo3GvpSM2kLZsmroq/0JWgEPByi7TkhwGDqnbDW9HE2NuQcEhR8ZcooS8ZJ40=

HTTP头内容：

LivingPayment-TimeStamp : 1564665789

LivingPayment-NonceStr : 5e680dac294cb6473cd2149bbbb48c43

LivingPayment-SignCertId : 5678

LivingPayment-EncryptCertId : 1234

LivingPayment-MchId : 14801922031（渠道商的商户号）