mirror of
https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat.git
synced 2025-12-29 18:04:42 +08:00
docs: 完善文档
This commit is contained in:
Fu Diwei
62
docs/WechatTenpayV3/Basic_Certificate2PublicKey.md
Normal file
62
docs/WechatTenpayV3/Basic_Certificate2PublicKey.md
Normal file
@@ -0,0 +1,62 @@
|
||||
## 如何从平台证书切换成公钥？
|
||||
|
||||
---
|
||||
|
||||
> 请先自行阅读：
|
||||
>
|
||||
> [《微信支付开发者文档 - 安全工具 - 如何从平台证书切换成微信支付公钥？》](https://pay.weixin.qq.com/doc/v3/merchant/4012154180)
|
||||
|
||||
---
|
||||
|
||||
### 基于平台公钥的 API 认证方式
|
||||
|
||||
自 v3.9.0 版本起，本库支持接入微信支付平台基于微信支付公钥的验证身份方式。
|
||||
|
||||
你只需要在原有的构造得到 `WechatTenpayClient` 对象的项目代码上做出调整，设置平台认证方案为“使用平台公钥认证”，并使用 `PlatformPublicKeyManager` 属性替代 `PlatformCertificateManager` 属性：
|
||||
|
||||
```csharp
|
||||
var manager = new Settings.InMemoryPublicKeyManager();
|
||||
manager.AddEntry(new PublicKeyEntry("公钥算法，目前仅支持 RSA 这一种类型", "公钥序列号（即 PubKeyID）", "PKCS#8 公钥内容"));
|
||||
|
||||
var options = new WechatTenpayClientOptions()
|
||||
{
|
||||
// 其他配置项略
|
||||
PlatformAuthScheme = Settings.PlatformAuthScheme.PublicKey,
|
||||
PlatformPublicKeyManager = manager
|
||||
};
|
||||
var client = WechatTenpayClientBuilder.Create(options).Build();
|
||||
```
|
||||
|
||||
后续加密或验签流程与原有方式完全一致。
|
||||
|
||||
> 延伸阅读：
|
||||
> - [如何加密请求中的敏感数据？](./Basic_RequestSensitiveDataEncryption.md)
|
||||
> - [如何验证响应签名？](./Basic_ResponseSignatureVerification.md)
|
||||
> - [如何验证回调通知事件签名？](./Basic_EventSignatureVerification.md)
|
||||
|
||||
---
|
||||
|
||||
### 平滑切换灰度兼容处理
|
||||
|
||||
在平滑切换灰度过程中，你需要同时兼容平台证书与平台公钥：
|
||||
|
||||
- 发送请求前，需要指定请求的 `WechatpaySerialNumber` 字段（即使该请求不包含敏感数据字段）。该操作会影响灰度进度中的“应答使用公钥比例”；
|
||||
- 验证签名时，需要根据响应或回调中的 `Wechatpay-Serial` 标头来判断是使用平台证书还是平台公钥。该操作受灰度进度中的“回调使用公钥比例”影响。
|
||||
|
||||
本库提供了简化处理方式，你只需要在构造得到 `WechatTenpayClient` 对象时：
|
||||
|
||||
```csharp
|
||||
var options = new WechatTenpayClientOptions()
|
||||
{
|
||||
// 其他配置项略
|
||||
PlatformAuthFallbackSwitch = true,
|
||||
PlatformAuthScheme = Settings.PlatformAuthScheme.PublicKey,
|
||||
PlatformCertificateManager = <your-manager>, // 需要同时设置 CertificateManager 与 PublicKeyManager
|
||||
PlatformPublicKeyManager = <your-manager>, // 需要同时设置 CertificateManager 与 PublicKeyManager
|
||||
};
|
||||
var client = WechatTenpayClientBuilder.Create(options).Build();
|
||||
```
|
||||
|
||||
这样一来，你无需在业务代码中增加额外的判断逻辑，本库会自动处理前面提到的兼容流程。
|
||||
|
||||
但需要注意的是，开启此特性后会带来一定的性能损失，因此建议仅在灰度切换期间时开启，待切换进度为百分之百后请关闭。
|
||||
@@ -19,7 +19,7 @@
|
||||
|
||||
如果你在开发过程出现验签不通过的情况，请先检查是否混淆了这两个证书。
|
||||
|
||||
🔥 另，2024 年 10 月后新注册的微信商户已不再提供平台证书，取而代之的是平台公钥。但二者的验签流程基本相同。更多内容请见本章的《适配微信支付新商户的平台公钥认证方式》一节。
|
||||
🔥 另，2024 年 10 月后新注册的微信商户已默认不再提供平台证书，取而代之的是平台公钥。但二者的验签流程基本相同。更多内容请见本章下文的《适配微信支付新商户的平台公钥认证方式》一节。
|
||||
|
||||
关于证书的更多注意事项，请参阅[《微信支付开发者文档 - 常见问题：证书相关》](https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay7_0.shtml)
|
||||
|
||||
@@ -67,6 +67,8 @@ if (!res.Result)
|
||||
|
||||
请参阅本文档[《基础用法 - 如何加密请求中的敏感数据？》](./Basic_RequestSensitiveDataEncryption.md)下的同名章节。
|
||||
|
||||
---
|
||||
|
||||
### 适配微信支付新商户的平台公钥认证方式
|
||||
|
||||
请参阅本文档[《基础用法 - 如何加密请求中的敏感数据？》](./Basic_RequestSensitiveDataEncryption.md)下的同名章节。
|
||||
请参阅本文档[《基础用法 - 如何从平台证书切换成公钥？》](./Basic_Certificate2PublicKey.md)。
|
||||
|
||||
@@ -23,7 +23,7 @@
|
||||
|
||||
关于证书的更多注意事项，请参阅[《微信支付开发者文档 - 常见问题：证书相关》](https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay7_0.shtml)
|
||||
|
||||
🔥 另，2024 年 10 月后新注册的微信商户已不再提供平台证书，取而代之的是平台公钥。但二者的加密流程基本相同。更多内容请见本章的《适配微信支付新商户的平台公钥认证方式》一节。
|
||||
🔥 另，2024 年 10 月后新注册的微信商户已默认不再提供平台证书，取而代之的是平台公钥。但二者的加密流程基本相同。更多内容请见本章下文的《适配微信支付新商户的平台公钥认证方式》一节。
|
||||
|
||||
---
|
||||
|
||||
@@ -229,21 +229,4 @@ public class RedisCertificateManager : ICertificateManager
|
||||
|
||||
### 适配微信支付新商户的平台公钥认证方式
|
||||
|
||||
自 v3.9.0 版本起，本库支持接入微信支付平台基于微信支付公钥的验证身份方式。
|
||||
|
||||
你只需要在原有的构造得到 `WechatTenpayClient` 对象的项目代码上做出调整，设置平台认证方案为“使用平台公钥认证”，并使用 `PlatformPublicKeyManager` 属性替代 `PlatformCertificateManager` 属性：
|
||||
|
||||
```csharp
|
||||
var manager = new Settings.InMemoryPublicKeyManager();
|
||||
manager.AddEntry(new PublicKeyEntry("公钥算法，目前仅支持 RSA 这一种类型", "公钥序列号（PubKeyID）", "PKCS#8 公钥内容"));
|
||||
|
||||
var options = new WechatTenpayClientOptions()
|
||||
{
|
||||
// 其他配置项略
|
||||
PlatformAuthScheme = Settings.PlatformAuthScheme.PublicKey,
|
||||
PlatformPublicKeyManager = manager
|
||||
};
|
||||
var client = WechatTenpayClientBuilder.Create(options).Build();
|
||||
```
|
||||
|
||||
后续流程与原有方式完全一致。
|
||||
请参阅本文档[《基础用法 - 如何从平台证书切换成公钥？》](./Basic_Certificate2PublicKey.md)。
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
|
||||
如果你在开发过程出现验签不通过的情况，请先检查是否混淆了这两个证书。
|
||||
|
||||
🔥 另，2024 年 10 月后新注册的微信商户已不再提供平台证书，取而代之的是平台公钥。但二者的验签流程基本相同。更多内容请见本章的《适配微信支付新商户的平台公钥认证方式》一节。
|
||||
🔥 另，2024 年 10 月后新注册的微信商户已不再提供平台证书，取而代之的是平台公钥。但二者的验签流程基本相同。更多内容请见本章下文的《适配微信支付新商户的平台公钥认证方式》一节。
|
||||
|
||||
关于证书的更多注意事项，请参阅[《微信支付开发者文档 - 常见问题：证书相关》](https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay7_0.shtml)
|
||||
|
||||
@@ -76,6 +76,8 @@ if (!res.Result)
|
||||
|
||||
请参阅本文档[《基础用法 - 如何加密请求中的敏感数据？》](./Basic_RequestSensitiveDataEncryption.md)下的同名章节。
|
||||
|
||||
---
|
||||
|
||||
### 适配微信支付新商户的平台公钥认证方式
|
||||
|
||||
请参阅本文档[《基础用法 - 如何加密请求中的敏感数据？》](./Basic_RequestSensitiveDataEncryption.md)下的同名章节。
|
||||
请参阅本文档[《基础用法 - 如何从平台证书切换成公钥？》](./Basic_Certificate2PublicKey.md)。
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
## 如何接入国密算法？
|
||||
## 如何从国际 RSA 证书切换成国密 SM 证书？
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
## 功能
|
||||
|
||||
- 基于微信支付 v3 版 API 封装。
|
||||
- 支持商户（直连模式）、合作伙伴（服务商、渠道商、机构、银行模式）两种角色模式。
|
||||
- 支持普通商户（直连）、合作伙伴（服务商、渠道商、机构、银行）两种接入模式。
|
||||
- 请求时自动生成签名（支持国际 RSA 算法或国密 SM 算法），无需开发者手动干预。
|
||||
- 提供了微信支付所需的 AES、RSA、SM2/SM3/SM4、SHA-256 等算法工具类。
|
||||
- 提供了调起支付签名、解析响应敏感数据、解析回调通知事件敏感数据等扩展方法。
|
||||
@@ -116,7 +116,9 @@ else
|
||||
|
||||
- [如何自定义额外的 API 接口？](./Basic_Extensions.md)
|
||||
|
||||
- [如何接入国密算法？](./Basic_SMAlgorithm.md)
|
||||
- [如何从平台证书切换成公钥？](./Basic_Certificate2PublicKey.md)
|
||||
|
||||
- [如何从国际 RSA 证书切换成国密 SM 证书？](./Basic_SMAlgorithm.md)
|
||||
|
||||
- [如何接入境外支付 API？](./Basic_GlobalAPI.md)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user