简介面向C#开发者的微信支付接口实战代码包聚焦微信支付、企业付款到个人及企业付款到零钱等典型场景适合需要对接微信商户平台、梳理支付与资金流转流程的中初级开发者参考。压缩包共93个文件约2.13MB以47个C#源码文件、13个ASPX页面、8个DLL程序集及5个配置文件为主辅以脚本、项目解决方案和少量说明文本能够覆盖Web端调用、接口封装与示例页面等层次。已有1575人学习下载。内容围绕JSAPI支付、刷卡与扫码支付、企业转账、订单退款、订单及退款查询、账单下载等接口展开并随包提供CS_SDK_v3.0.9相关封装与示例工程读者可据此理解预支付会话获取、签名验证、请求发送与结果处理等关键环节也便于对照现有项目排查参数配置、回调处理和对账流程中的常见问题。1. 企业付款到零钱不是“转账接口”C# DEMO 里最值钱的是状态机很多人拿到一份 C# 微信支付 的企业付款到零钱 DEMO第一反应是翻出那个发 HTTP 请求的方法改个金额、换个 openid 就准备上线。真跑起来才发现卡住的地方几乎从来不在请求那几行签名过了、接口返回 200、状态却停在“处理中”隔两天对账发现钱没到账也不知道该从哪查起。微信转账 这类资金类接口本质是一套“发起—受理—确认—回调—对账”的状态机而不是一次普通的下单。这份 DEMO 适合两类人一是手里已有商户号、要在 C# 后台做佣金/报销/提现打款的后端二是接手了老项目、需要把存量 v2 接口迁到 v3 签名体系的维护者。下面按“接口选型—签名—单笔—批量—排错—验证”的顺序拆每段都给能直接抄的代码。2. 证书、密钥与签名APIv3 请求在 C# 里怎么拼才不返 401签名这一层是整套链路里最容易反复翻车的地方因为它不涉及业务逻辑报错信息却只有一句 401 或者一个 SIGN_ERROR。先把选型和密钥材料说清楚再动手写代码能省掉大半天。2.1 三条链路的差异先选对接口再动手同一个“企业付钱给个人”的需求落到接口上是三条完全不同的链路字段、限额、开通条件都不一样。我一般先让需求方确认收款的载体是零钱还是银行卡再决定写哪个客户端否则代码写完发现资质没开白干。维度商家转账到零钱v3企业付款到银行卡普通收款JSAPI/APP/Native资金方向商户 → 用户零钱商户 → 用户银行卡用户 → 商户关键入参openid、金额、场景 ID银行卡号、户名、开户行商品描述、金额敏感字段姓名需平台证书加密卡号、姓名均需加密无到账时效一般实时或分钟级受银行处理影响T0/T1 都有实时常见限制需单独开通产品权限、有日出额上限需额外签约、手续费规则不同无调试难度中状态机 回调高银行侧返回码多低选型上有一条血泪经验能用零钱链路解决的别碰银行卡链路。银行卡接口对户名、开户行、卡号三者一致性要求极严一个字的差异就是银行退票退款周期还长零钱链路失败时资金原路退回试错成本低得多。另外旧项目里还大量存在 v2 版本的付款接口走的是双向证书、MD5/HMAC 签名和 v3 的 RSA 体系是两套东西迁移时不要混着写两套 HttpClient 配置分开维护更省心。2.2 从 p12 里抠出证书序列号.NET 的字节序坑v3 签名需要一个商户 API 证书和它的序列号材料通常是 apiclient_cert.p12 加一个密码。加载本身不难难的是序列号取出来之后和平台侧对不上很多人就是在这里第一次翻车。using System.Security.Cryptography; using System.Security.Cryptography.X509Certificates; public static (X509Certificate2 Cert, RSA PrivateKey, string SerialNo) LoadMerchantCert( string p12Path, string password) { // MachineKeySet 让证书私钥落到机器密钥容器避免 IIS 应用程序池回收后私钥不可用 var cert new X509Certificate2( p12Path, password, X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.Exportable); var rsa cert.GetRSAPrivateKey() ?? throw new InvalidOperationException(证书中没有 RSA 私钥确认导入的是 apiclient_cert.p12); // 关键SerialNumber 属性返回的十六进制在部分运行时上顺序与平台展示不一致 // .NET 5 直接用 GetSerialNumberString()老框架手动反转字节再拼接 #if NET5_0_OR_GREATER var serial cert.GetSerialNumberString().ToUpperInvariant(); #else var raw cert.GetSerialNumber(); // 小端字节数组 Array.Reverse(raw); var serial BitConverter.ToString(raw).Replace(-, string.Empty).ToUpperInvariant(); #endif return (cert, rsa, serial); }这段的逻辑是先用 p12 密码解出带私钥的证书对象再单独把 RSA 私钥拿出来复用最后生成和平台控制台显示一致的序列号。参数上有三点要注意MachineKeySet是为了让站点在多进程、多应用池的环境下都能读到私钥不加的话本地控制台跑得好好的部署到服务器就报“私钥不存在”Exportable不是必须的但如果你要做多节点部署、把证书导入到容器镜像里留着它后面迁移不折腾序列号统一转大写是因为不同版本运行时输出的十六进制大小写不一样签名头里大小写不一致也会被判失败。还有一点证书有有效期且平台证书和商户证书是两码事。商户证书用来签你发出去的请求平台证书用来验平台回来的应答和回调。前者从 p12 读后者要通过证书下载接口拉取并且要缓存、定期轮换——直接写死在配置文件里的项目半年后一定会遇到回调验签失败。2.3 Authorization 头五行签名串一个字符都不能错v3 的签名规则说穿了很简单把方法、URL、时间戳、随机串、请求体拼成五行每行以换行结尾做 SHA256 摘要后用商户私钥 RSA 签名再塞进 Authorization 头。但“简单”和“能过”之间隔着好几个字符级细节。using System.Security.Cryptography; using System.Text; public static string BuildAuthorization( HttpMethod method, // GET / POST string urlPath, // 形如 /v3/fund-app/mch-transfer/transfer-bills含 query 但不含域名 string body, // POST 的原始 JSON 字符串GET 传空串 string mchId, string serialNo, RSA privateKey) { var timestamp DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(); var nonce Guid.NewGuid().ToString(N); // 32 位无连字符 // 签名串固定五行结尾必须带换行body 为空的 GET 请求也要保留那一行 var message ${method.Method}\n{urlPath}\n{timestamp}\n{nonce}\n{body}\n; var signature Convert.ToBase64String(privateKey.SignData( Encoding.UTF8.GetBytes(message), HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1)); return $WECHATPAY2-SHA256-RSA2048 mchid\{mchId}\,nonce_str\{nonce}\, $signature\{signature}\,timestamp\{timestamp}\,serial_no\{serialNo}\; }逻辑说明签名对象不是 body 本身而是那串拼好的五行文本SignData内部已经做了 SHA256不需要你再手动哈希一次重复哈希是新手最常见的错。参数上有几个硬约束urlPath必须和实际发出去的路径逐字符一致query 参数要按你最终发送的顺序写进去中途用字典重新拼一次参数就会导致签名与请求不匹配timestamp是秒级 Unix 时间戳和服务器时间偏差过大平台会直接拒绝容器里时钟没同步的项目要留意RSASignaturePadding.Pkcs1不能写成 PSS平台只认 PKCS#1 v1.5。nonce用 GUID 去掉连字符足够了它只要求随机、不要求加密强度。真正需要随机性的是每次请求都重新生成不要复用同一个 nonce 加时间戳做“缓存签名”那等于把重放窗口焊死在代码里。2.4 一个能复用的签名请求封装把上面两块拼起来再套一层 HttpClient才是能反复调用的东西。我习惯做一个薄客户端把签名、超时、应答解析都收在一处业务代码只传路径和 DTO。public class WxPayClient { private readonly HttpClient _http; private readonly RSA _privateKey; private readonly string _mchId; private readonly string _serialNo; public WxPayClient(HttpClient http, RSA privateKey, string mchId, string serialNo) { _http http; _privateKey privateKey; _mchId mchId; _serialNo serialNo; _http.BaseAddress new Uri(https://api.mch.weixin.qq.com); _http.Timeout TimeSpan.FromSeconds(10); // 资金类接口别设太长重试比死等更划算 } public async Task(int Status, string Body) PostAsync(string path, string jsonBody) { using var req new HttpRequestMessage(HttpMethod.Post, path); req.Content new StringContent(jsonBody, Encoding.UTF8, application/json); req.Headers.TryAddWithoutValidation( Authorization, BuildAuthorization(HttpMethod.Post, path, jsonBody, _mchId, _serialNo, _privateKey)); req.Headers.TryAddWithoutValidation(Accept, application/json); using var resp await _http.SendAsync(req); var text await resp.Content.ReadAsStringAsync(); return ((int)resp.StatusCode, text); } }这段的重点不在代码本身而在几个容易忽略的默认值。BaseAddress不要带尾斜杠路径自己带前导斜杠否则拼出来的 URL 会出现双斜杠签名用的是你写的 path、实际请求的是另一个 URL401 会来得莫名其妙。超时设 10 秒左右是因为资金类接口在平台侧偶发慢响应客户端等 60 秒既占线程又没意义配合业务层的幂等键做重试更实际。应答体一定要先读完再返回哪怕状态码是 4xx——错误详情全在 body 里只记状态码的日志等于没记。还有一处常被忽视HttpClient要用单例或者IHttpClientFactory管理别在方法里 new。资金类接口 QPS 不高但连接泄漏在长跑服务里迟早会咬你一口。3. 单笔转账到零钱从参数加密到回调解密的完整链路单笔转账看起来只是一次 POST实际上前后各挂着一层前面要做敏感字段加密后面要做回调解密与验签。这两层缺一个接口要么直接报错要么回调收到了却处理不了。3.1 请求体字段openid、金额、场景 ID 与敏感字段加密先把字段讲清楚再谈代码。金额单位是分不是元这是最经典的单位错误来源out_bill_no是商户侧单号必须全局唯一重复提交会直接命中幂等返回transfer_scene_id决定这笔钱的业务性质不同场景对应的限额和可用性不一样填错虽然能受理但对账和对客解释都会很别扭。字段类型必填说明out_bill_nostring是商户单号建议业务类型日期序列长度控制在 32 内transfer_scene_idstring是转账场景标识按实际业务选择不能随手填openidstring是收款用户在对应 appid 下的 openidtransfer_amountint是金额单位分整数transfer_remarkstring是转账备注用户可见transfer_scene_report_infosarray视场景场景报备信息部分场景要求填写user_namestring否收款人姓名明文不可直传需平台证书公钥加密notify_urlstring否回调地址不传则依赖主动查询user_name这一行是 C# 开发者的高频翻车点。平台要求用 RSA/OAEP 填充加密而 .NET 的RSA.Encrypt默认参数是 PKCS#1 v1.5直接调就是密文解不开。using System.Security.Cryptography; using System.Security.Cryptography.X509Certificates; using System.Text; // 用平台证书公钥加密敏感字段填充必须是 OAEP-SHA1 public static string EncryptSensitiveField(string plain, X509Certificate2 platformCert) { using var rsa platformCert.GetRSAPublicKey() ?? throw new InvalidOperationException(平台证书不含公钥); var cipher rsa.Encrypt(Encoding.UTF8.GetBytes(plain), RSAEncryptionPadding.OaepSHA1); return Convert.ToBase64String(cipher); }逻辑很直白拿平台证书里的公钥按 OAEP-SHA1 加密后转 Base64 塞进字段。参数上两个坑要记牢填充模式写成OaepSHA256在部分链路里会被判解密失败平台侧约定的是 SHA1平台证书要从证书下载接口拉最新的不要用商户证书去加密——这两张证书长得像用途完全不同。3.2 发起转账的完整调用字段和加密都齐了调用本身反而简单。我一般把 DTO 序列化成紧凑 JSON不要带缩进和多余空格因为这个字符串同时用于签名和请求体两边必须字节一致。public async Taskstring TransferAsync(WxPayClient client, X509Certificate2 platformCert, TransferRequest dto) { // 敏感字段先加密再序列化序列化选项必须和签名用的一致 if (!string.IsNullOrEmpty(dto.UserName)) dto.UserName EncryptSensitiveField(dto.UserName, platformCert); var json JsonSerializer.Serialize(dto, new JsonSerializerOptions { DefaultIgnoreCondition JsonIgnoreCondition.WhenWritingNull, // 空字段不传避免校验失败 Encoder JavaScriptEncoder.UnsafeRelaxedJsonEscaping // 中文备注不要被转成 \uXXXX }); var (status, body) await client.PostAsync(/v3/fund-app/mch-transfer/transfer-bills, json); if (status ! 200) throw new WxPayException($转账受理失败 status{status} body{body}); return body; // 里面含 transfer_bill_no 和 statestate 才是你要落库的东西 }这段代码里序列化选项比请求本身更值得看。WhenWritingNull是为了不把一堆null字段发上去平台对某些字段的“传了但不合法”和“没传”处理方式不同UnsafeRelaxedJsonEscaping是为了让中文备注原样落库默认转义虽然不影响平台解析但日志里看着难受排查时多一层心智负担。返回值里最关键的不是 HTTP 200而是 body 里的state。受理成功只代表平台接了这个单子钱有没有到用户零钱是另一回事这个状态必须落库后面所有查询、对账、客服答疑都靠它。3.3 查询、撤销与“处理中”状态机我在生产上见过最典型的事故是把“处理中”当成失败然后重新发起结果用户收到两笔钱人工追回。资金类接口的状态必须当成状态机来设计而不是当成布尔值。// 按商户单号查询返回 state 可能是受理中 / 处理中 / 成功 / 失败 / 已撤销 public async Taskstring QueryAsync(WxPayClient client, string outBillNo) { var path $/v3/fund-app/mch-transfer/transfer-bills/out-bill-no/{outBillNo}; var (status, body) await client.GetAsync(path); // GetAsync 内部用空 body 签名 if (status 404) return NOT_FOUND; // 单号不存在可能是还没落库 return body; }这里的参数逻辑值得展开查询走的是商户单号而不是平台单号是因为你的数据库里只有商户单号落库时把平台返回的transfer_bill_no一并存下即可两条路都能查。404 在查询接口里不是异常是“这笔单子我这边没有”常见于发起请求超时但实际未受理的情况业务上应该走“先查后补”而不是直接判失败。撤销接口只在特定状态下可用一般是受理中或处理中且用户尚未确认收款。我一般把撤销做成管理后台的手动按钮不做自动调用——自动撤销在并发场景下容易和用户确认收款撞车状态判断再准也有窗口期。3.4 回调验签与 AES-256-GCM 解密回调是整个链路里最容易被简化处理的部分很多人验签直接跳过或者解不出来就把回调当通知靠定时查询兜底。能跑但等于放弃了实时性而且一旦有人构造假回调打你的接口业务状态会被污染。using System.Security.Cryptography; using System.Text; using System.Text.Json; public static string DecryptNotify(string apiV3Key, string associatedData, string nonce, string ciphertextBase64) { var key Encoding.UTF8.GetBytes(apiV3Key); // 必须 32 字节 var nonceBytes Encoding.UTF8.GetBytes(nonce); // 12 字节 var data Convert.FromBase64String(ciphertextBase64); // 密文尾部 16 字节是 tag var cipher data.AsSpan(0, data.Length - 16); var tag data.AsSpan(data.Length - 16); var plain new byte[cipher.Length]; #if NET6_0_OR_GREATER using var aes new AesGcm(key, 16); // .NET 8 起必须显式传 tag 长度 aes.Decrypt(nonceBytes, cipher, tag, plain, string.IsNullOrEmpty(associatedData) ? null : Encoding.UTF8.GetBytes(associatedData)); #else // .NET Framework 没有 AesGcm用 BouncyCastle 的 GCMBlockCipher 实现同一套参数 throw new PlatformNotSupportedException(请引入 BouncyCastle 或升级到 .NET 6); #endif return Encoding.UTF8.GetString(plain); }参数说明是这段的核心apiV3Key是你在商户平台单独设置的 32 位密钥不是证书密码也不是 mchidnonce是回调报文里的明文随机串不是 Base64ciphertext是 Base64解码后最后 16 字节是认证标签前面才是密文associatedData参与认证传错或者传空都会导致解密抛异常而不是返回乱码。.NET Framework 项目在这里会直接卡住因为AesGcm只在 .NET Core 之后才有存量项目要么引 BouncyCastle要么把回调服务单独拆一个 .NET 6 的进程我一般选后者边界干净。验签则要在解密之前做取回调头里的时间戳、随机串和原始报文拼成三行文本用平台证书公钥验 RSA-SHA256 签名。注意必须用原始报文不能反序列化再序列化一次字段顺序变了签名就废了。4. 批量转账与付款到银行卡两套接口的边界与幂等设计单笔跑通之后需求方通常会提两个新要求一次发给几百个人以及“有人没有零钱账户能不能直接打银行卡”。这两件事对应两套接口混用会出问题。4.1 批量转账批次号、明细与失败明细下载批量转账的思路是“先建批次再传明细”批次是一层壳明细是壳里的条目。批次号out_batch_no全局唯一明细里每条也有自己的商户单号两个层级都要做幂等。// 第一步创建批次拿到 platform_batch_no var batchJson JsonSerializer.Serialize(new { out_batch_no B20240101001, batch_name 一月佣金发放, batch_remark 内部结算, total_amount 150000, total_num 100 }); var (s1, b1) await client.PostAsync(/v3/transfer/batches, batchJson); // 第二步逐条或分批上传明细明细单号在批次内唯一 var detailJson JsonSerializer.Serialize(new { out_detail_no B20240101001-0001, transfer_amount 1500, transfer_remark 一月佣金, openid USER_OPENID_PLACEHOLDER }); var (s2, b2) await client.PostAsync($/v3/transfer/batches/out-batch-no/B20240101001/details, detailJson);逻辑上要注意顺序批次创建成功不代表能立刻传明细也不代表金额校验会通过total_amount和total_num是声明值实际明细汇总对不上会在后续处理中被判失败。参数上out_detail_no建议直接用批次号加序号拼天然保证批次内唯一跨批次也不会撞。明细里失败的条目不会让整批失败平台会生成失败明细供下载。我的习惯是在批次状态变为“处理完成”后主动拉一次失败明细把失败原因余额不足、账户异常、姓名不符等写回业务表让业务侧自己决定要不要重发而不是程序自动重试——重试在批量场景下会把失败率放大成资金风险。4.2 付款到银行卡为什么它和零钱是两套东西付款到银行卡是另一套接口体系入参是卡号、户名、开户行标识敏感字段全部要加密而且对开户行的编码有固定字典。它和零钱链路最大的区别在于银行侧返回码语义复杂同一个“失败”背后可能是户名不符、卡号不存在、账户冻结、银行维护处理策略完全不同。var bankJson JsonSerializer.Serialize(new { out_bill_no K20240101001, bank_card_no EncryptSensitiveField(cardNo, platformCert), // 卡号加密 true_name EncryptSensitiveField(realName, platformCert), // 姓名加密 bank_code bankCode, // 必须用平台字典里的编码 amount 50000, remark 报销款 });参数上最容易错的是bank_code。很多人拿银行名称或者自己维护的编码去填接口能受理处理结果是“开户行不支持”。这个字典要单独拉取并缓存不要硬编码在枚举里——银行列表是会变的。另外银行卡链路的到账不是实时的state长时间停在处理中是常态业务侧的话术和超时判断要跟零钱链路分开配。还有一点银行卡付款通常伴随手续费和单独的结算规则财务对账时金额要和零钱链路的流水分开统计混在一张表里做日终对账差异永远平不掉。4.3 幂等键怎么设计out_batch_no 与 transfer_bill_no资金接口的重试是必须做的但重试的前提是幂等。平台侧的幂等靠的是你传的单号同一单号重复提交平台返回第一次的结果不会重复出款。我的做法是三层单号业务单号订单/佣金记录 ID、商户请求单号out_bill_no或out_batch_no、平台单号transfer_bill_no。业务单号在业务库里唯一约束生成商户请求单号时带上业务类型前缀和日期落库时三列一起存唯一索引加在业务单号上。// 幂等写入先插本地流水表唯一索引冲突说明已发起过直接查平台状态 try { await _db.InsertAsync(new TransferRecord { BizNo dto.BizNo, OutBillNo dto.OutBillNo, State INIT, Amount dto.Amount, CreatedAt DateTime.UtcNow }); } catch (DuplicateKeyException) { // 命中本地幂等不重复调用平台 return await QueryAsync(client, dto.OutBillNo); }这段的顺序很关键先落本地再调平台。反过来的话请求发出去了但本地入库失败重试时单号变了就是双倍出款。中间的异常窗口用“落库成功但请求超时”兜底——这时候单号已经固定重试或者查询都指向同一笔不会产生第二笔资金。5. 避坑与排查签名 401、状态卡在处理中、额度超限的五种现场前面几章都是“应该怎么做”这一章讲“做完了不对怎么办”。下面五条都是我在真实项目里反复遇到的现场按现象、原因、解决三段写方便对照日志直接定位。5.1 签名与证书类现场现象一所有接口一律返回 401body 里是SIGN_ERROR但本地用同样参数算出来的签名和日志里的完全一致。原因基本锁定在签名串的 URL 部分。常见情况是用了HttpRequestMessage.RequestUri的完整地址去做签名里面带了协议和域名或者路径里的 query 参数被 HttpClient 重新排序、编码了一次。还有一种更隐蔽的网关或反向代理改写了路径业务代码签的是/v3/xxx实际发出去的是/api/v3/xxx。解决方式是把“参与签名的路径”和“实际请求的路径”解耦签名前用一个常量拼路径不要从请求对象反推。发请求时确认没有中间件在改写 URL容器化部署的项目要看一眼 ingress 的 rewrite 规则。排查时把签名串原文打到日志里注意脱敏 body逐行和平台文档比对通常一眼就能看出多了一个换行或者少了一个斜杠。现象二本地调试正常部署到服务器后所有请求报“私钥不存在”或签名直接抛异常。原因是证书加载时用了X509KeyStorageFlags.DefaultKeySet私钥被放进了用户配置文件而 IIS 应用程序池或 Windows 服务跑在另一个账户下读不到。另一种是容器镜像里只 COPY 了 p12 文件没有对应的密钥容器权限。解决方式是加载时统一加MachineKeySet并且不要用Exportable之外的临时标志。容器场景更稳的做法是把 p12 以文件形式挂载启动时加载到内存并缓存RSA实例避免每次请求都读盘。加载失败时把cert.HasPrivateKey打出来比猜快得多。现象三回调偶尔验签失败重试后又正常日志里看不出规律。原因是验签用的是反序列化之后再序列化的 body。JSON 序列化器会改变字段顺序、空格、转义方式签名的原文和平台发的原文已经不是同一个字节序列。并发低的时候因为缓存或者巧合没暴露流量一上来就变成随机失败。解决方式是回调入口第一件事就是读原始请求体存成字符串后续验签、解密、业务解析全部基于这个字符串。ASP.NET Core 里要用EnableBuffering并回绕流位置MVC 里不要用模型绑定直接接参数。这一步做完回调失败率会直接降到零。5.2 业务状态与额度类现场现象四转账发起成功状态一直停在“处理中”查询接口也返回处理中用户反复来问钱到没到。原因有两种。一种是用户侧还没确认收款部分转账场景需要用户在客户端点确认这个阶段平台侧就是处理中急也没用另一种是回调没收到或者收到了但处理失败业务表状态没更新看起来像卡住。解决方式是把“平台状态”和“业务状态”分开存。业务状态由回调驱动回调没来就靠定时任务主动查询兜底查询频率按状态分级——刚发起的几分钟查一次超过一定时间降频。对客话术也要按状态给别把处理中说成失败也别承诺具体到账时间。我一般会加一个“超过 N 小时仍在处理中”的告警人工介入比程序瞎猜靠谱。现象五批量转账提交时报额度或频率超限单笔却是好的。原因是批量接口有独立的单批次限额和日累计限额而且和单笔共享同一个产品的日额度池。另一种情况是同一批次内明细条数超过单次上传上限需要分页上传。解决方式是先查产品权限里的额度配置把批量拆成可控的小批次并在业务侧做一个本地额度计数器发之前先自检不要等平台拒绝。分页上传时注意每页的明细单号保持唯一且连续重传同一页时靠明细单号做幂等不要用“第几页”做标识。提示所有资金类接口的报错日志里必须同时记录 HTTP 状态码、业务错误码、请求单号和平台返回的原始报文。只记一句“转账失败”的日志排错时要花十倍时间去复现。6. 上线前用 0.01 元把链路验穿一份自检清单和一个对账脚本代码写完、单测跑过不代表能上线。资金链路的验证必须在真实环境做而且要小额、可回滚、有记录。我的习惯是上线前用 0.01 元跑一遍完整链路从发起到回调到查询到对账全部走通再放量。6.1 一份照着勾的自检表下面这张表是我每次接支付项目都会过一遍的顺序不要跳因为后面的项依赖前面的结果。顺序检查项通过标准1商户证书加载服务启动日志能打印出序列号和有效期HasPrivateKey为 true2平台证书拉取与缓存启动后能拉到证书序列号与回调验签用的一致3签名自检用一个查询接口验证返回 200 而非 4014敏感字段加密姓名加密后发起平台不报解密失败5单笔 0.01 元转账受理成功状态最终变为成功用户侧到账6回调接收回调到达、验签通过、解密成功、业务表状态更新7主动查询兜底手动关掉回调入口定时任务能把状态查回来8幂等重试同一单号重复提交平台返回同一笔本地不产生第二条流水9对账本地流水与平台账单金额、笔数一致10告警处理中超时、验签失败、余额不足三类事件能触发告警第 6 项和第 7 项要分开验很多人回调通了就不再测主动查询结果回调服务一挂状态就永远停在中间态。第 8 项最容易被跳过恰恰是资金事故的高发点。6.2 一个够用的对账脚本对账不需要多复杂把平台账单下载下来和本地流水按商户单号做一次全量比对差异分三类输出就够了本地有平台无、平台有本地无、金额不一致。前两类通常是超时重试或人工补单留下的痕迹第三类必须当天查清。// 按 out_bill_no 做全量比对输出三类差异日终跑一次 var localMap localRecords.ToDictionary(x x.OutBillNo, x x.Amount); var remoteMap remoteBills.ToDictionary(x x.OutBillNo, x x.Amount); var onlyLocal localMap.Keys.Except(remoteMap.Keys).ToList(); // 本地有平台无 var onlyRemote remoteMap.Keys.Except(localMap.Keys).ToList(); // 平台有本地无 var mismatch localMap.Keys.Intersect(remoteMap.Keys) .Where(k localMap[k] ! remoteMap[k]) .Select(k ${k}: local{localMap[k]}, remote{remoteMap[k]}) .ToList();参数上只有一个要点比对键必须用商户单号不要用平台单号。因为平台单号在受理后才生成超时未受理的单子本地根本没有用平台单号比对会把这些单子漏掉而它们恰恰是最需要人工确认的那批。“本地有平台无”的单子先看本地状态是不是停在“发起中”是的话走查询确认“平台有本地无”的单子看是不是别的系统或人工后台发的确认来源后补录。这三类差异每天清零资金链路才算真正可控。从那以后我每次接资金类需求不管需求方怎么催都会先把那笔 0.01 元的转账在预发环境跑通、把对账脚本挂上定时任务再谈功能。这套流程救过我两次一次是回调验签被中间件改了 body一次是批量单号重复导致重发。希望帮到你。本文还有配套的精品资源点击获取
