开发接入检查用例
更新时间:2026.11.181[ 2 { 3 "id": "recreate_order_when_h5_url_expires", 4 "category": [ 5 "数据一致性", 6 "工程质量" 7 ], 8 "title": "`h5_url` 有效期为 5 分钟,超时须用原下单参数重新下单", 9 "text": "说明:h5_url 的有效期为 5 分钟,该有效期指支付跳转链接本身的有效期,并非要求用户在 5 分钟内完成付款;超过有效期须使用原下单参数重新请求下单接口获取新的 h5_url。正确应该怎么做:① 在用户实际发起支付时再调用 H5 下单接口获取 h5_url,避免提前长时间缓存;② 若用户在链接生成 5 分钟后才发起支付,用原下单参数重新调用下单接口换取新的 h5_url 后再跳转;典型反例:提前批量预生成 h5_url 并长时间缓存复用。**不做会怎么样**:超过 5 分钟后访问提示「支付请求已失效,请重新发起支付」,用户需要重新下单才能继续付款。见 [4012791834-H5下单](https://iwiki.woa.com/p/4012791834)、[4012791831-H5支付开发指引](https://iwiki.woa.com/p/4012791831)、[4012791845-H5支付常见问题](https://iwiki.woa.com/p/4012791845)。" 10 }, 11 { 12 "id": "common_sign_verify_crypto", 13 "category": [ 14 "工程质量" 15 ], 16 "title": "签名、验签、加解密抽成公共方法", 17 "text": "把签名、验签、敏感字段加解密、回调验签与解密抽成公共方法。业务接口调用这一份,不要在各接口里各写一套。默认使用官方工具类(Java [`WXPayUtility`](https://iwiki.woa.com/p/4014931831)、Go [`wxpay_utility`](https://iwiki.woa.com/p/4015119334))配合 API 列表请求示例实现(知识库内各接口请求示例即基于该工具类,且原生支持微信支付公钥),非 java、go 语言可参考示例进行实现;工程已依赖官方 SDK、或经用户明确选定 SDK 时才使用 SDK,两种方式都须满足本项单点维护要求。" 18 }, 19 { 20 "id": "sign_wechat_pay_api_requests", 21 "category": [ 22 "资金安全" 23 ], 24 "title": "调用微信支付接口要签名", 25 "text": "APIv3 用商户 API 证书私钥签名并写入 `Authorization`。`serial_no` 填商户 API 证书序列号,不填平台证书序列号或微信支付公钥 ID。见 [4012365342-总述-APIv3如何签名和验签](https://iwiki.woa.com/p/4012365342)。APIv2 按参数名 ASCII 序签名,空值不参与,签名写入 `sign`。见 [4011985891-安全规范](https://iwiki.woa.com/p/4011985891)。" 26 }, 27 { 28 "id": "verify_response_and_callback_signatures", 29 "category": [ 30 "资金安全" 31 ], 32 "title": "应答和回调都要验签", 33 "text": "应答和回调先验签,通过后再使用。**存在验签方法不等于验签生效**;须核对每个调用点确实调用,且验签失败即中止,不是只记日志继续执行。验签失败如何处理见 [4013053249-如何使用微信支付公钥验签](https://iwiki.woa.com/p/4013053249)。" 34 }, 35 { 36 "id": "match_callback_and_query_with_local_order", 37 "category": [ 38 "资金安全" 39 ], 40 "title": "回调与查单结果必须与本地订单核对一致", 41 "text": "验签只证明报文来自微信支付,不证明这笔钱属于这笔订单。**验签通过不等于可以直接入账**;须用通知或查单返回的商户订单号定位本地订单,核对金额、商户号、`appid` 与订单归属后才能更新状态。外部交易号须完整持久化,防止串单或被覆盖。见 [4012075420-回调通知注意事项](https://iwiki.woa.com/p/4012075420)。" 42 }, 43 { 44 "id": "do_not_skip_signature_probe_verification", 45 "category": [ 46 "资金安全" 47 ], 48 "title": "签名探测流量不得跳过验签或直接当成功", 49 "text": "`Wechatpay-Signature` 以 `WECHATPAY/SIGNTEST/` 开头是探测流量。仍要验签。验签失败后应答舍弃,回调返回 `4xx` 或 `5xx`。见 [4013053249-如何使用微信支付公钥验签](https://iwiki.woa.com/p/4013053249)。" 50 }, 51 { 52 "id": "keep_secrets_on_server_only", 53 "category": [ 54 "资金安全" 55 ], 56 "title": "密钥只留服务端,不得泄露到任何外部可获取的位置", 57 "text": "商户 API 私钥、证书、APIv3 密钥、APIv2 密钥只留在服务端,从环境变量或 KMS 加载,**不得硬编码**。禁止进入源码、仓库、日志、接口响应和可被 URL 直接访问的目录。疑似泄露立即更换;从仓库删除不能使已泄露密钥失效。**使用环境变量或 KMS 不等于密钥安全**;还须核对配置是否随仓库分发、读取权限,以及日志与异常是否回显密钥内容。见 [4012073693-密钥泄漏修复指引](https://iwiki.woa.com/p/4012073693)。" 58 }, 59 { 60 "id": "encrypt_sensitive_fields_per_api_doc", 61 "category": [ 62 "资金安全" 63 ], 64 "title": "敏感字段加解密按接口文档逐字段执行", 65 "text": "哪些字段需加密、用公钥还是平台证书,以该接口文档的字段说明为准(含 `Wechatpay-Serial` 请求头应传公钥 ID 还是平台证书序列号,与 `Authorization` 中的商户证书序列号不是同一个);应答中的密文用商户私钥解密。" 66 }, 67 { 68 "id": "use_backend_values_for_critical_fields", 69 "category": [ 70 "资金安全" 71 ], 72 "title": "资金 / 关键字段一律以后端为准,严禁相信前端传值", 73 "text": "调用微信 API 的金额、商户号、用户标识、业务类型等关键字段必须从可信后端数据源读取;前端传入仅作为引导,不能直接落库或入参。下单金额由服务端计算,不采用前端传入的金额。" 74 }, 75 { 76 "id": "use_integer_cents_for_amounts", 77 "category": [ 78 "资金安全" 79 ], 80 "title": "金额全程使用整数分,不经过浮点", 81 "text": "接口金额单位为分且必须是整数。从计价、优惠扣减、累加到落库与接口入参,全程使用整数或精确十进制类型;**在最后一步转为整数分不等于精度安全**——只要中间任一环节用过 `float`/`double`,误差已经产生。同时核对舍入方式、负值、零值与溢出边界。见 [4012068676-参数说明](https://iwiki.woa.com/p/4012068676)。" 82 }, 83 { 84 "id": "do_not_treat_client_success_as_paid", 85 "category": [ 86 "资金安全" 87 ], 88 "title": "前端返回成功不能当作支付成功", 89 "text": "用户在页面或 App 上看到的支付结果,只表示收银台流程结束,不能据此把订单改成已支付。是否支付成功,要由商户后端调用微信支付查单接口确认:`trade_state` 为 `SUCCESS`。**调用查单接口不等于确认**;须核对确实判断了 `trade_state`,且查单失败或超时时不得按成功处理。见 [4012075249-支付回调和查单实现指引](https://iwiki.woa.com/p/4012075249)。" 90 }, 91 { 92 "id": "do_not_skip_server_certificate_checks", 93 "category": [ 94 "资金安全" 95 ], 96 "title": "不得忽略服务端证书校验错误", 97 "text": "请求走 HTTPS,不得为图方便关闭或跳过服务端证书校验(如 trust-all)。见 [4012081709-基本规则](https://iwiki.woa.com/p/4012081709)。" 98 }, 99 { 100 "id": "retry_with_original_order_and_params", 101 "category": [ 102 "数据一致性" 103 ], 104 "title": "重试必须使用原单号且原参数", 105 "text": "微信支付接口支持幂等。超时或失败后重试,单据沿用第一次的单号和全部参数,不要换单号或改参数。要修改内容时,先结束原单,再换新单号。" 106 }, 107 { 108 "id": "process_each_business_order_once", 109 "category": [ 110 "数据一致性" 111 ], 112 "title": "同一笔业务只能处理一次", 113 "text": "1)**以业务完成状态为唯一幂等判据,判定与写入须原子完成**:重复可能来自回调重发、查单结果、重试应答等任意来源,不靠来源区分,一律以业务自身的完成状态(如订单已支付)判定;判定与写入须由条件更新或数据库唯一约束一次完成。**通知 ID 去重不等于业务幂等**(只防同一条通知重复到达);**仅「先查状态再更新」不能证明并发安全**;**独立去重标记不得替代业务状态作为判据**——标记写入不代表业务已完成,否则业务失败后重发被误判为已处理,该单永不收敛。2)**幂等命中仍须应答成功**:重复到达不再执行业务,但仍应答 200/204,**不得以抛异常表达「已处理过」**而被转成 5xx。未在 5 秒内应答微信会判失败并重发,故业务处理耗时须与应答窗口解耦(先应答再异步处理)。见 [4012075420-回调通知注意事项](https://iwiki.woa.com/p/4012075420)。" 114 }, 115 { 116 "id": "prevent_duplicate_payment_orders", 117 "category": [ 118 "数据一致性" 119 ], 120 "title": "防止重复下单(前端与服务端都要做)", 121 "text": "**前端**:付款按钮点击后立即置为不可点并提示处理中,本次下单有结果后再恢复。**服务端**:以业务订单为幂等粒度——同一业务订单(合并支付时为同一组业务订单)重复发起支付,须复用已有商户订单号及有效期内的 `prepay_id`,不得生成第二个商户订单号;原商户订单号确认已关闭或失效后才可换新。用户确实要再买一次时会产生新的业务订单,服务端无需猜测意图。**按请求或页面会话去重不等于按业务订单去重**;同一业务订单只要可能产生第二个商户订单号,即不通过。两者不可互相替代——只做防抖,网络延迟、多端操作或接口被直接调用时失效;只做服务端去重,用户连点时仍会感到卡顿、出现异常。见 [4012791870-JSAPI支付开发指引](https://iwiki.woa.com/p/4012791870)。" 122 }, 123 { 124 "id": "set_timeouts_and_bounded_retries", 125 "category": [ 126 "工程质量" 127 ], 128 "title": "对外调用必须设超时,重试必须有界", 129 "text": "每个微信支付调用都要设连接与读取超时,不得无限等待;**代码里有 try-catch 不等于有超时控制**,未显式配置的 HTTP 客户端多数默认无限等待。失败后区分结果不确定(超时、网络中断)与明确失败(参数、鉴权错误):前者走查单收敛,不直接判失败;后者不重试。**重试须有明确终止条件**:按查单收敛的重试,终止于结果明确或业务时效到期(如订单 `time_expire`、流程规则给定的时间窗);不得无条件无限重试,也不得仅以次数上限代替收敛。" 130 }, 131 { 132 "id": "query_order_when_notification_missing", 133 "category": [ 134 "工程质量" 135 ], 136 "title": "异步通知缺失时主动查单", 137 "text": "支付、退款、扣款、分账都要有后台主动查单,不能只等异步通知;实现方式不限(回调异常时查单、定时任务、延时队列等均可),但须由后台自己发出,**仅靠用户回到页面时前端触发不算**。**存在查单代码不等于覆盖**;扫描窗口须覆盖单据有效期,到期须有关单或终止动作,以内存队列作唯一事实来源的会永久漏单,须说明待处理单如何被完整发现。见 [4012075249-支付回调和查单实现指引](https://iwiki.woa.com/p/4012075249)。" 138 }, 139 { 140 "id": "failover_and_failback_api_domains", 141 "category": [ 142 "工程质量" 143 ], 144 "title": "配置主备域名,异常时自动切换并在恢复后回切", 145 "text": "主备域名双活,备域名保持少量流量。主域名异常时自动把主通道切到备域名,恢复后回切。**配置两个域名不等于具备容灾**;须有按故障判断实际切换的代码路径,由网关或基础设施实现的需提供配置证据,仅声明记「未验证」。见 [4012075113-跨城冗灾升级指引](https://iwiki.woa.com/p/4012075113)。" 146 }, 147 { 148 "id": "use_field_names_from_current_api_doc", 149 "category": [ 150 "接入规范" 151 ], 152 "title": "字段名与取值以该接口文档为准", 153 "text": "写请求、解析应答或回调前,先读当前接口文档里的字段名,按文档原文使用。不要凭其他接口、命名习惯或记忆去猜大小写和下划线。例如:服务端下单用 `appid`,JSAPI 调起支付用 `appId`。选填字段没有值时不要传 `null` 或 `\"\"`。见 [4012081709-基本规则](https://iwiki.woa.com/p/4012081709)。" 154 }, 155 { 156 "id": "parse_responses_without_assuming_order", 157 "category": [ 158 "接入规范" 159 ], 160 "title": "应答解析兼容性", 161 "text": "不假设 JSON 键值对的出现顺序;不强校验应答结构,新增字段不得导致解析失败或拒绝该笔应答。见 [4012081709-基本规则](https://iwiki.woa.com/p/4012081709)。" 162 }, 163 { 164 "id": "branch_on_http_status_and_code", 165 "category": [ 166 "接入规范" 167 ], 168 "title": "按 HTTP 状态码和 `code` 处理,禁止按 `message` 做逻辑判断", 169 "text": "`message` 是可变文案,同一 `code` 可对应多条 `message`,按它分支会在文案变更时失效。见 [4012081717-HTTP状态码](https://iwiki.woa.com/p/4012081717)。" 170 }, 171 { 172 "id": "log_request_id_without_secrets", 173 "category": [ 174 "工程质量" 175 ], 176 "title": "成功和失败都记录 Request-ID,且不记录敏感明文", 177 "text": "成功和失败都记录应答头 `Request-ID`,并关联商户订单号。见 [4012081709-基本规则](https://iwiki.woa.com/p/4012081709)。不得记录密钥和敏感明文。" 178 }, 179 { 180 "id": "notify_url_must_be_public", 181 "category": [ 182 "接入规范" 183 ], 184 "title": "下单必须传入公网可访问的 `notify_url`", 185 "text": "`notify_url` 须为公网可访问地址。传入内网地址或地址错误时,收不到支付成功回调。见 [4012075420-回调通知注意事项](https://iwiki.woa.com/p/4012075420)。" 186 }, 187 { 188 "id": "debounce_and_reuse_existing_order", 189 "category": [ 190 "接入规范" 191 ], 192 "title": "前端下单按钮须防抖,服务端须防止同一笔业务重复下单", 193 "text": "前端对同一笔业务重复提交时,服务端应识别为同一次下单,而不是再受理一笔新单。`prepay_id` 未满 2 小时,用原参数调起;已满 2 小时,用原 `out_trade_no` 和原参数重新下单。见 [4012791856-JSAPI/小程序下单](https://iwiki.woa.com/p/4012791856)。" 194 }, 195 { 196 "id": "prepay_id_expires_in_two_hours", 197 "category": [ 198 "接入规范" 199 ], 200 "title": "`prepay_id` 有效期 2 小时", 201 "text": "`prepay_id` 有效期 2 小时。超过后须用原下单参数重新请求下单接口,不得用已过期的 `prepay_id` 调起。见 [4012791856-JSAPI/小程序下单](https://iwiki.woa.com/p/4012791856)。" 202 }, 203 { 204 "id": "invoke_appid_must_match_order", 205 "category": [ 206 "接入规范" 207 ], 208 "title": "调起参数 `appId` 须与下单 `appid` 一致", 209 "text": "`appId` 须与下单接口传入的 `appid`、当前公众号 `appid` 一致。不一致时无法调起,或提示账号不一致。见 [4012791857-JSAPI调起支付](https://iwiki.woa.com/p/4012791857)。" 210 }, 211 { 212 "id": "require_time_expire", 213 "category": [ 214 "接入规范" 215 ], 216 "title": "下单必须传入 `time_expire`", 217 "text": "`time_expire` 是用户能完成支付的最后时限,下单时必须传入。未传时,超过 7 天未支付的订单无法再支付。见 [4012791856-JSAPI/小程序下单](https://iwiki.woa.com/p/4012791856)。" 218 }, 219 { 220 "id": "query_before_close_or_refund", 221 "category": [ 222 "接入规范" 223 ], 224 "title": "用户取消或超时未支付时,先查单再决定关单或退款", 225 "text": "先查单。`NOTPAY` 才关单。`SUCCESS` 不关单:用户取消走退款,超时则先履约,无法履约再退款。`NOTPAY` 不得直接置为支付失败。见 [4012075249-支付回调和查单实现指引](https://iwiki.woa.com/p/4012075249)。" 226 }, 227 { 228 "id": "confirm_payment_on_backend", 229 "category": [ 230 "接入规范" 231 ], 232 "title": "支付结果须以后端查单或支付成功回调为准", 233 "text": "`get_brand_wcpay_request:ok` 只表示用户完成收银台操作,不表示支付成功。更新为已支付及发货,仅当查单或支付成功回调验签通过且 `trade_state` 为 `SUCCESS`。见 [4012075249-支付回调和查单实现指引](https://iwiki.woa.com/p/4012075249)。" 234 }, 235 { 236 "id": "ack_callback_within_five_seconds", 237 "category": [ 238 "接入规范" 239 ], 240 "title": "支付成功回调须在 5 秒内应答,未收到时须查单", 241 "text": "收到通知后 5 秒内先验签再应答。验签不通过返回 `4xx` 或 `5xx`,不得返回 `200`。未收到通知时查单同步状态。见 [4012075420-回调通知注意事项](https://iwiki.woa.com/p/4012075420)。" 242 }, 243 { 244 "id": "do_not_reorder_before_query", 245 "category": [ 246 "接入规范" 247 ], 248 "title": "未收到支付成功回调时不得立即再次下单", 249 "text": "未收到回调时先查单,不得更换 `out_trade_no` 再次下单。`trade_state` 为 `NOTPAY` 不表示支付失败。见 [4012791856-JSAPI/小程序下单](https://iwiki.woa.com/p/4012791856)。" 250 }, 251 { 252 "id": "allow_wechat_callback_ip_ranges", 253 "category": [ 254 "接入规范" 255 ], 256 "title": "防火墙须放行微信支付回调 IP 段", 257 "text": "支付成功回调来自微信支付回调 IP。该 IP 被拦截时收不到通知,须放行其访问 `notify_url` 的 443 端口。见 [4012075420-回调通知注意事项](https://iwiki.woa.com/p/4012075420)。" 258 }, 259 { 260 "id": "set_apiv3_key_for_callbacks", 261 "category": [ 262 "接入规范" 263 ], 264 "title": "未设置 APIv3 密钥时无法接收支付成功回调", 265 "text": "商户平台未设置 APIv3 密钥时,微信支付不向 `notify_url` 推送支付成功回调。见 [4012072195-配置APIv3密钥](https://iwiki.woa.com/p/4012072195)。" 266 }, 267 { 268 "id": "integrate_order_query", 269 "category": [ 270 "接入规范" 271 ], 272 "title": "不得漏接查单", 273 "text": "「商户订单号查询订单」与「微信支付订单号查询订单」至少接入一个。两个都不接时,无法确认订单支付状态。见 [4012791859-商户订单号查询订单](https://iwiki.woa.com/p/4012791859)。" 274 }, 275 { 276 "id": "refund_apply_idempotent_and_confirm", 277 "category": [ 278 "资金安全" 279 ], 280 "title": "接入退款时须完成申请、幂等、结果确认和状态持久化", 281 "text": "同一 `out_refund_no` 多次请求只退一笔。退款申请返回成功只表示已受理,标为退款成功只依据回调 `REFUND.SUCCESS` 或查单 `status` 为 `SUCCESS`。见 [4013071036-申请退款](https://iwiki.woa.com/p/4013071036)。" 282 }, 283 { 284 "id": "query_refund_and_retry_original_no", 285 "category": [ 286 "资金安全" 287 ], 288 "title": "退款申请超时或状态不明时须查询,重试须使用原退款单号", 289 "text": "超时或返回 `SYSTEM_ERROR` 等状态未明时,调用查询单笔退款确认状态。重试须使用原 `out_refund_no`,更换退款单号可能导致重复退款。见 [4012791863-查询单笔退款(通过商户退款单号)](https://iwiki.woa.com/p/4012791863)。" 290 }, 291 { 292 "id": "handle_abnormal_refund", 293 "category": [ 294 "资金安全" 295 ], 296 "title": "须处理全部退款结果,`ABNORMAL` 须调用发起异常退款", 297 "text": "`ABNORMAL` 表示原路退回银行卡失败,须调用发起异常退款。未调用时,资金停留在退款中间账户。见 [4012791864-发起异常退款](https://iwiki.woa.com/p/4012791864)。" 298 }, 299 { 300 "id": "refund_eta_is_not_settlement", 301 "category": [ 302 "资金安全" 303 ], 304 "title": "退款到账时间只用于向用户说明预期,不作为结单依据", 305 "text": "退款有一定延时。零钱支付的订单退款一般 5 分钟内到账,银行卡支付的订单退款一般 1-3 个工作日到账。这是预计到账时间,只用来向用户说明,不能据此把退款标成成功。是否成功,以查询退款返回的 `status` 为准。见 [4013071031-订单退款开发指引](https://iwiki.woa.com/p/4013071031)。" 306 }, 307 { 308 "id": "configure_refund_notify_url", 309 "category": [ 310 "资金安全" 311 ], 312 "title": "退款回调地址至少配置一处", 313 "text": "可在退款申请传入 `notify_url`,或在商户平台配置退款回调,至少一处。接口传入 `notify_url` 后,商户平台配置的回调地址不再生效。见 [4013071036-申请退款](https://iwiki.woa.com/p/4013071036)。" 314 }, 315 { 316 "id": "apply_then_download_bill_and_verify_hash", 317 "category": [ 318 "数据一致性" 319 ], 320 "title": "对账须先申请账单再下载,并核验 `hash_value`", 321 "text": "申请交易账单、申请资金账单只返回 `download_url`,不返回账单数据。下载后将文件摘要与 `hash_value` 比对。见 [4012791866-申请交易账单](https://iwiki.woa.com/p/4012791866)。" 322 }, 323 { 324 "id": "reconcile_trade_bill_with_local_orders", 325 "category": [ 326 "数据一致性" 327 ], 328 "title": "交易账单须与本地订单逐笔核对", 329 "text": "下载并核验 `hash_value` 后,按订单与本地逐笔比对。微信支付成功但本地未成功的差异须有处理,不能只下载不核对。见 [4012791868-下载账单](https://iwiki.woa.com/p/4012791868)。" 330 } 331]
文档是否有帮助
