36 KiB
陪诊订单微信支付接入方案
更新时间:2026-11-05 状态:资金安全评审(第二轮)+ 微信支付接入规范评审已完成,修复项已并入,待实施 2026-11-05 增补:下单页可选微信支付 / 线下支付,支付方式写入订单并支持待支付期间切换(线下支付不细分现金/转账,由平台补记);支付/退款异常统一兜底,错误详情(code/message/requestId)落库 2026-11-05 资金评审修复:①取消待支付订单必须关单;②回调收到支付但订单已取消时自动退款;③关单失败改为当场查单确认(不依赖本期不做的巡检);④存在未决流水时禁止改价;⑤一单多流水、商户单号不重用;⑥退款结果保留管理端手动查单兜底 2026-11-05 取消规则调整:用户端只保留「取消订单」(无删除入口)。待确认且未收款取消即物理删除;已确认或已收款转
cancel_requested,由该单陪诊师(限本人名下)或管理员确认后正式取消,不物理删除,已收款的同步进入退款 2026-11-05 接入规范评审修订:①下单显式传time_expire(支付窗口有边界);②prepay 过期沿用原单号重下,仅旧流水已关闭/失效才换新号;③补收银链路超时设置;④退款未成功应答先查退款、原单号重试一次;⑤同一订单发起支付串行化,防两条在途流水;⑥回调分支补cancel_requested,回调研启退款改在应答之后;⑦补后台轻量巡检查单/超时关单,回调丢失可收敛
一、背景与现状
- C 端小程序(
ui/wxapp_escort)下单流程已上线:itemorder提交订单 →escort_record落库(status: pending、payment.status: unpaid) - 当前收款为客服协助线下完成,支付方式由平台在收款时补记(
offline_cash/offline_transfer) - 本期目标:用户在小程序内直接完成线上微信支付,取消已支付订单自动原路退款
- 微信支付商户号已在官方申请完成
现状要点(代码侧):
| 现状 | 位置 |
|---|---|
payment 已预留 online_wechat 方法枚举与 unpaid/partial/paid/refunding/refunded 状态 |
api/health/models/schema/escort_record.js |
openid 已在登录时经 jscode2session 存入 user.app["wxapp-escort"].wxopenid,与小程序 appid 天然一致 |
api/user/handler/users.js |
服务价格以字符串元存储("500.00"),订单 totalFee 为数字元 |
api/health/resource/services.js |
线上域名 api.huashengtec.com(HTTPS),nginx 同域分流 /health → 9004,回调地址可直接复用 |
ui/wxapp_escort/utils/config.js、api/health/nginx_site.txt |
二、接入要素(已确认)
| 要素 | 结论 | 说明 |
|---|---|---|
| 支付产品 | 小程序支付 | JSAPI 下单(POST /v3/pay/transactions/jsapi)+ wx.requestPayment 调起 |
| 商户角色 | 普通商户 | 直连模式,报文只带 mchid / appid |
| API 版本 | APIv3 | JSON 报文 + RSA-SHA256 签名;APIv2 已存量维护,不新接 |
| 验签方式 | 微信支付公钥 | PUB_KEY_ID_ 格式序列号,长期有效免轮换 |
| 支付交互 | 下单选支付方式 → 微信支付立即拉起收银台 | 下单页可选「微信支付 / 线下支付」;选微信支付则下单成功后立即调起收银台,选线下支付则直接跳订单列表。列表/详情页保留「去支付」与「修改支付方式」入口 |
| 支付时限 | 下单传 time_expire |
显式给出可支付窗口,默认下单后 24 小时(且不晚于服务开始当天);取值须落在下单后 1 分钟 ~ 15 天内,超出会被微信自动调整。窗口以下单时间为起点固定计算,不随重新发起支付延长;到期订单不可再用微信支付,只能改线下或取消,到期流水由巡检关单 |
| 线上退款 | 本期实现 | 取消已支付订单自动调退款 API 原路退回 |
| SDK | Node 内置 crypto 自实现 | 官方仅提供 Java/Go/PHP SDK;签名/验签/AES-GCM 解密用 node:crypto + node-fetch,无新依赖 |
三、整体业务流程
下单时先选支付方式,两条分支:
用户下单(itemorder 选择支付方式)
├─ 微信支付 ─> createRecord(payment.payChannel=online_wechat, status=unpaid)
│ └─ 下单成功后立即发起支付(见下方链路)
└─ 线下支付 ─> createRecord(payment.payChannel=offline, status=unpaid)
└─ 直接跳订单列表,等待平台收款后补记实际收款方式
微信支付链路:
用户(小程序) health后端 微信支付
│ 1.点"去支付"/下单成功 │ │
│ ─────────────────> │ POST /escort-record/:id/pay
│ │ 2.校验(本人/待支付/未付款) │
│ │ 3.写 payment_record(created) │
│ │ 4.JSAPI下单(金额=分, openid, time_expire, out_trade_no=订单_id-序号)
│ │ ─────────────────────> │ 返回 prepay_id(有效期2小时)
│ │ 5.更新流水 prepayId+过期时间 │
│ │ 6.私钥签名生成 paySign │
│ 7.返回调起支付五参数 │ <───────────────────── │
│ <───────────────── │ │
│ 8.wx.requestPayment 调起收银台 ───────────────────>│
│ │ │ 用户完成支付
│ 9.前端回调(不可信) │ │
│ ─────────────────> │ 10.查单接口:主动调微信查单确认 │
│ │ ─────────────────────> │ trade_state=SUCCESS
│ │ 11.更新流水 pay_success → 刷订单快照 paid
│ 12.返回支付结果 │ │
│ <───────────────── │ │
│ │ 13.支付成功回调(异步,权威) │
│ │ <───────────────────── │ 验签+解密+金额校验
│ │ 14.更新流水+订单快照,幂等应答200 │
回调到达时的订单状态判定(关键分支):
支付成功回调(验签 + 解密 + 字段校验通过)
├─ 订单 status ∈ {pending, confirmed} 且 payment.status = unpaid
│ └─ 流水 pay_success → 刷订单快照 paid,正常进入履约
├─ 订单 status = cancel_requested(用户已申请取消、尚未确认)
│ └─ 同上:钱已到账就按已支付如实记账,不提前退款;后续确认取消时按取消流程原路退款
└─ 订单 status = cancelled(订单已正式取消)
├─ 流水仍落 pay_success(钱确实到账,是财务事实,不能丢)
├─ 订单快照保持 cancelled,不刷 paid(避免「已取消订单显示已收款」)
└─ 应答 200 之后再异步发起原路全额退款(写 refund_record(processing) → 调退款接口),不在应答前调外部接口
退款流程(取消已支付线上订单时自动触发):
用户申请取消 ──> updateStatus(cancelled) ──> status = cancel_requested
└─ 陪诊师/管理员确认取消 ──> updateStatus(cancelled)
├─ 1.先写 refund_record(processing) ← 先落库再调接口
├─ 2.调微信退款 API(POST /v3/refund/domestic/refunds)
├─ 2.1 调用异常/超时 → 先查退款确认是否受理:未受理则用同一 outRefundNo 原参数重试一次;仍失败保持 processing 转人工
├─ 3.订单快照 payment.status = refunding
└─ 4.退款回调(REFUND.SUCCESS) ─> refund_record(success) ─> 订单快照 refunded
后台巡检查单(回调丢失的唯一兜底)
- 服务启动时注册单一定时器,默认运行(不靠人工开启);每 10 分钟扫一次
payment_record.status ∈ {created, closed_unconfirmed},按创建时间限定在最近 7 天内,避免全表扫描 created流水:按outTradeNo查单SUCCESS→ 按回调同一套逻辑收敛(流水pay_success+ 刷订单快照;订单已取消则转退款)NOTPAY且已过timeExpireAt→ 关单,流水置closed- 查单失败 → 记
lastError,下一轮重试
closed_unconfirmed流水:查单确认,未支付则补记closed,已支付则按退款处理
官方开发指引的核心原则:
- 前端回调不可信:
requestPayment回调后必须以后端查单结果为准 - 回调是权威:验签 → AES-256-GCM 解密 → 校验
out_trade_no与金额 → 落库 → 5 秒内应答 200;重复推送做幂等(已处理直接 200) - 防重复支付:前端按钮防抖 + 服务端以「当前有效流水」为幂等粒度(prepay_id 未过期直接复用;过期但窗口内用原单号重下;旧流水已关闭或窗口到期才换新
outTradeNo,唯一索引兜底)
支付方式选择与流转
字段拆分:把「用户选择的支付方式意向」与「实际收款方式」分开记录,避免把还没收到的钱记成已按某方式收款。用户端只提供「微信支付 / 线下支付」两个选项;线下支付不细分现金/转账,实际收款方式由平台收款时补记为 offline_cash 或 offline_transfer。
| 字段 | 取值 | 含义 | 写入方 |
|---|---|---|---|
payment.payChannel |
online_wechat / offline |
用户下单时选择的支付渠道 | 下单时写入;待支付期间用户可自助修改 |
payment.method |
"" / online_wechat / offline_cash / offline_transfer |
实际收款方式 | 线上支付成功后由回调写入;线下由平台收款时补记 |
状态矩阵:
| 场景 | payChannel | method | payment.status | 列表/详情展示 |
|---|---|---|---|---|
| 选微信支付,尚未支付(含中途取消) | online_wechat | "" |
unpaid | 「待支付」+「去支付」 |
| 选微信支付,超过支付窗口未付 | online_wechat | "" |
unpaid | 「支付已超时」,无「去支付」,仅可改线下或取消 |
| 微信支付成功 | online_wechat | online_wechat | paid | 「已支付」 |
| 选线下支付,平台尚未收款 | offline | "" |
unpaid | 「线下支付,待收款」 |
| 线下收款完成,平台补记 | offline | offline_cash / offline_transfer | paid | 「已支付(现金/转账)」 |
| 线上已支付后取消 | online_wechat | online_wechat | refunding → refunded | 「退款中 / 已退款」 |
| 线下已收款后取消 | offline | offline_cash / offline_transfer | refunding | 「退款中」(线下人工退款核销) |
| 用户申请取消(已确认或已收款) | 保持原值 | 保持原值 | 保持原值 | 「待取消」,等待陪诊师/管理员确认 |
取消规则(用户端只保留「取消订单」按钮):
- 待确认且未收款:用户取消后订单直接物理删除,无需二次确认
- 已确认或已收款:用户取消后订单进入
cancel_requested(待取消),不物理删除;由该订单的陪诊师或管理员确认后才转为cancelled,已收款的同步进入退款流程 cancel_requested期间用户不可再次取消、不可修改支付方式;陪诊师只能确认自己名下的订单,管理员不限- 已取消、已完成为终态,不可再取消
修改支付方式规则:
- 允许时机:订单
status ∈ {pending, confirmed}且payment.status = unpaid(未收到钱之前都可改) - 用户端在订单详情页切换
payChannel:online_wechat↔offline - 改回
online_wechat后再次「去支付」时,必须使用新的商户订单号(订单_id + "-" + 新尝试序号),不复用已关闭的单号 - 已支付(
paid/refunding/refunded)、cancel_requested或已进入服务中(in_progress)的订单,一律不可修改支付方式
关单是切换与取消的前置动作(防止旧 prepay_id 在 2 小时内仍被支付,造成「订单已取消 / 已改线下,钱却进来了」):
切换为线下 / 取消订单 / 支付窗口到期
└─ 存在 payment_record(created)
├─ 1.调用微信关单接口
├─ 2.关单成功 → 流水置 closed
└─ 3.关单失败 → 立即调查单接口确认(不等巡检)
├─ trade_state = SUCCESS → 实际已付款:中止本次切换/取消,
│ 提示「订单已支付」,转入退款流程
└─ 未支付 / 查单也失败 → 流水置 closed_unconfirmed 并放行,
交对账核对(订单仍按用户意愿处理)
关单失败时「当场查单一次」是立即兜底;仍未确认的中间态由后台巡检查单收敛(见第五节)。
支付异常处理(统一兜底 + 错误落库)
原则:不按异常类型做差异化业务分支,所有外部异常统一兜底、统一提示;但错误详情必须落库,供财务与运维排查。
异常来源与处理:
| 阶段 | 典型异常 | 处理方式 |
|---|---|---|
| JSAPI 下单 | 网络超时、连接失败、APPID_MCHID_NOT_MATCH、MCHID_NOT_EXISTS、SIGN_ERROR、NO_AUTH 等 |
记录流水 lastError;订单保持 unpaid;前端提示可重试或改用线下支付 |
| 查单 | 同上 | 记录 lastError;前端按最后一次已知状态展示 |
| 关单 | 同上 | 记录 lastError;当场查单一次确认,已支付则中止切换/取消并转退款(见本节关单流程) |
| 退款 | 商户余额不足、参数错误、网络异常 | 记录 refund_record.lastError;超时/系统异常先查退款:确认未受理则同一 outRefundNo 原参数重试一次;明确业务错误(余额不足等)直接转人工,保持 processing |
| 回调验签/解密/字段校验 | 验签失败、解密失败、mchid / appid / currency / 金额与本地不一致 |
logger 记录并应答 4XX/5XX,不落业务库(报文不可信,不能作为数据来源) |
落库字段(payment_record / refund_record 共用同一结构):
lastError: {
stage: String, // create 下单 / query 查单 / close 关单 / refund 退款
code: String, // 网络异常固定 NETWORK_ERROR;微信侧错误取应答 code;HTTP 异常记状态码
message: String, // 微信返回 message 或系统异常原文,截断 500 字符
requestId: String, // 微信应答头 Request-ID,向微信侧排查时提供
httpStatus: Number, // HTTP 状态码,网络异常时为 0
at: Date // 发生时间
},
errorCount: Number, // 累计失败次数,用于识别反复失败
lastAttemptAt: Date, // 最近一次调用时间
统一封装约定(utils/wechatpay.js):
- 所有微信 API 调用异常统一抛
WechatPayError,字段固定为{ stage, code, message, requestId, httpStatus } - 所有请求显式设置连接/读取超时(默认 5 秒);超时与连接中断按「结果不确定」处理,走查单收敛,不直接判失败
- 网络/SDK 异常 →
code = "NETWORK_ERROR",message保留原始错误文本 - HTTP 非 2XX →
code/message取微信应答体,requestId取响应头 message统一截断 500 字符,避免超长文本撑库
前端统一处理:
payOrder请求失败 → 提示「支付发起失败,请稍后重试;如持续失败可改用线下支付」wx.requestPayment返回requestPayment:fail cancel→ 提示「已取消支付」,订单保持待支付- 其他 fail → 先调查单兜底(可能支付已成功但网络中断),再按查单结果提示
- 不区分错误码,不向用户暴露内部错误详情
四、数据模型设计(对账导向)
设计原则:订单与支付分离,流水是事实源
escort_record (业务订单) payment_record (支付流水) refund_record (退款流水)
├─ status: 服务履约状态 ├─ outTradeNo 商户订单号 ├─ outRefundNo 商户退款单号
└─ payment: 汇总快照(展示用) ├─ transactionId 微信支付订单号 ├─ refundId 微信退款单号
unpaid/paid/refunded... ├─ 金额(分)/状态机/事件时间戳 ├─ 金额(分)/状态/入账账户
└─ 每次支付尝试一条文档 └─ 一次退款一条文档
- 流水表为财务事实源:状态每次变更落时间戳,链路完整可审计
- 订单上的
payment保留为汇总快照:列表/详情展示免 join,写完流水后同步刷新 - 金额全链路用「分」(int):与微信账单口径一致,杜绝元/分浮点误差,只在展示层转元;由
service.price字符串(如"500.00")直接解析为整数分(按小数点拆位,不做元 × 100浮点运算),换算收敛在支付模块单点
payment_record(支付流水)
{
// 业务关联
bizType: "escort", // 业务类型,后续培训报名等复用
recordId: ObjectId, // 关联 escort_record._id
userId: ObjectId, // 付款用户(按用户查支付历史)
// 微信侧标识(对账核心字段)
outTradeNo: String, // 商户订单号 = 订单_id + "-" + 尝试序号,唯一索引(永不重用)
attemptNo: Number, // 第几次支付尝试(从 1 起),区分同单多次发起
transactionId: String, // 微信支付订单号,唯一稀疏索引(支付成功后回填)
prepayId: String, // 预支付会话标识
prepayExpiresAt: Date, // prepay_id 过期时间(2小时,复用判断)
timeExpireAt: Date, // 下单传入的 time_expire(支付窗口终点)
// 渠道信息(与微信账单核对的维度)
appid: String,
mchid: String,
tradeType: "JSAPI",
// 金额(分)
totalFee: Number, // 应付金额
payerTotal: Number, // 用户实付(券后,回调回填)
// 状态机 + 事件时间戳(审计链)
status: "created", // created → pay_success / closed
// created → closed_unconfirmed(关单失败且查单未确认)
// pay_success → refunding → refunded
closeUnconfirmed: Boolean, // 关单结果不确定时置 true,进人工核对
createdAt, prepayedAt, paidAt, closedAt,
// 支付成功回调关键留档(审计/争议处理)
bankType: String, // 支付方式(如 OTHERS/CMB_CREDIT)
successTime: Date, // 微信侧支付完成时间
// 异常留档(任何外部异常都记,不区分类型,结构见第三节「支付异常处理」)
lastError: { stage, code, message, requestId, httpStatus, at },
errorCount: Number, // 累计失败次数
lastAttemptAt: Date, // 最近一次调用时间
meta: { createtime, updatetime }
}
// 索引:{ outTradeNo: 1 } unique、{ transactionId: 1 } unique sparse、
// { recordId: 1 }、{ userId: 1, createdAt: -1 }
流水粒度规则(一单可多条,单号不重用):
- 同一订单每次重新发起支付都新建一条流水,
outTradeNo递增后缀(-1、-2…),不复用已关闭的单号 - 订单
payment.paymentRecordId指向「当前有效」的那条流水;历史流水保留作为审计 - 单条流水在 prepay_id 有效期内重复点「去支付」时直接复用,不新建
- prepay_id 已过期但仍在支付窗口内:沿用该流水与同一
outTradeNo、原下单参数重新下单,刷新prepayId/prepayExpiresAt,不新建流水 - 只有该流水已
closed(关单成功)或已超出timeExpireAt(微信侧不可再付)才新建流水换新号 - 财务核对以
outTradeNo为键:一单多次尝试对应多个未支付单号 + 至多一笔成功
refund_record(退款流水)
{
paymentId: ObjectId, // 关联 payment_record
recordId: ObjectId, // 冗余关联订单
outTradeNo: String, // 原商户订单号(冗余)
outRefundNo: String, // 商户退款单号 = 订单_id + "-R1",唯一索引
refundId: String, // 微信退款单号,唯一稀疏索引
refundAmount: Number, // 退款金额(分)
totalAmount: Number, // 原订单金额(分)
reason: String, // 退款原因(= 订单取消原因)
status: "processing", // processing → success / abnormal / closed
userReceivedAccount: String, // 退款入账账户(回调返回,客服答疑用)
successTime: Date,
lastQueriedAt: Date, // 最近一次主动查询退款结果的时间(回调丢失时的兜底依据)
// 异常留档(退款失败可查原因,如商户余额不足)
lastError: { stage, code, message, requestId, httpStatus, at },
errorCount: Number,
lastAttemptAt: Date,
meta: { createtime, updatetime }
}
对账场景
| 对账场景 | 做法 |
|---|---|
| 日常对账 | 下载微信交易账单 → 按 transactionId / outTradeNo 逐笔与 payment_record 核对金额与状态;退款笔目对 refund_record |
| 状态差异 | 回调丢失导致流水停在中间态 → 后台巡检查单补齐(见第三节);T+1 再用交易账单人工核对 |
| 客诉/争议 | bankType + successTime + 完整时间戳链还原每笔交易过程 |
| 用户查"我付了哪笔" | userId + createdAt 索引直接查流水 |
| 退款卡单 | 退款回调丢失导致长期停在 processing → 管理端「查询退款结果」调退款查单接口,补写 success / abnormal |
| 关单未确认 | 流水 closed_unconfirmed → 按 outTradeNo 查单确认终态,补记 closed;若已支付则转退款 |
本期退款约束:一笔支付只发起一次全额退款(outRefundNo = 订单_id + "-R1"),不支持部分退款;重试必须沿用同一 outRefundNo(微信对同号退款幂等返回原退款单);退款结果除回调外,由管理端手动查询兜底。
五、后端改动清单(api/health)
| # | 文件 | 内容 |
|---|---|---|
| 1 | utils/wechatpay.js(新增) |
APIv3 请求签名、应答/回调验签(含 WECHATPAY/SIGNTEST/ 探测流量处理)、AES-256-GCM 回调解密、JSAPI 下单/查单/关单/退款调用、调起支付 paySign 生成、Request-ID 日志;所有调用异常统一抛 WechatPayError(结构见第三节) |
| 2 | models/schema/payment_record.js(新增) |
支付流水,见第四节 |
| 3 | models/schema/refund_record.js(新增) |
退款流水,见第四节 |
| 4 | handler/payment.js(新增) |
createPayment(校验金额 > 0 / 订单状态 / 未支付 / 未超支付窗口 → 无有效流水时新建 outTradeNo → 落流水 → 微信下单 → 返回五参数,prepay 有效期内复用、过期用原单号重下)、queryPayment(主动查单落流水+刷快照)、paymentNotify(验签→解密→校验 mchid/appid/currency/金额→按订单状态分支写流水→应答 200→已取消订单再异步发起退款)、refundNotify、queryRefund(管理端查退款结果兜底);所有外部异常统一捕获,写入 lastError / errorCount / lastAttemptAt 后再返回通用错误提示;退款异常先查退款、未受理则原单号重试一次;同一订单的 createPayment 按 recordId 串行(进程内锁),防止并发产生两条在途流水;模块内提供巡检函数,服务启动时注册定时器默认运行 |
| 5 | handler/escort_record.js(改造) |
① createRecord:接收用户端 payment.payChannel(仅 online_wechat / offline,默认 online_wechat),method 留空待支付成功或平台补记;管理员代客下单仍可指定 method。② updateRecord:为用户端放开 payment.payChannel,仅 pending / confirmed 且 unpaid 可改;存在 created 流水的订单禁止修改 payment.totalFee(要调价先关单)。③ 切换为线下:关单 + 失败当场查单确认,已支付则拒绝切换并转退款。④ updateStatus 取消:未确认且未收款 → 物理删除;已确认或已收款 → cancel_requested,陪诊师/管理员确认后转 cancelled,线上已收款订单再走退款流程;线下收款订单维持原人工退款。⑤ 金额 ≤ 0 的订单禁止发起线上支付;⑥ 支付窗口到期由巡检关单,流水置 closed |
| 6 | routes/index.js |
POST /escort-record/:id/pay(requireAuth + createLimit 限流)、GET /escort-record/:id/pay/status(requireAuth)、POST /escort-record/:id/refund/query(requireAdmin,退款查单兜底)、POST /pay/notify、POST /pay/refund-notify(后两条无鉴权,微信服务器直调,靠验签保安全;注册在 /:id 路由之前防抢占) |
| 7 | models/schema/escort_record.js |
payment 保持汇总快照角色:新增 payChannel(用户选择的支付渠道)与 paymentRecordId(指向当前有效流水);method 语义收窄为「实际收款方式」;其余细节字段移入流水表 |
| 8 | conf.json |
新增 wechatpay 配置段(结构占位,密钥部署时填系统级配置 /etc/ehason/conf.json,APIv3 密钥走环境变量,不进仓库) |
配置段结构:
"wechatpay": {
"mchid": "",
"appid": "",
"merchantSerial": "",
"privateKeyPath": "",
"apiv3KeyEnv": "WXPAY_APIV3_KEY",
"publicKeyId": "",
"publicKeyPath": "",
"notifyBase": "https://api.huashengtec.com/health",
"payWindowHours": 24
}
六、前端改动清单(ui/wxapp_escort + 管理端)
| # | 文件 | 内容 |
|---|---|---|
| 1 | utils/api.js |
escort 段新增 payOrder(id)、getPayStatus(id) |
| 2 | pages/escort/itemorder.js |
新增支付方式选择(微信支付 / 线下支付,默认微信支付);提交订单时带 payment.payChannel。选微信支付:下单成功 → 立即 payOrder → wx.requestPayment → 查单确认 → 按结果跳转;选线下支付:下单成功后直接跳订单列表并提示线下支付 |
| 3 | pages/escort/recordlist / recorddetail |
unpaid 订单按 payChannel 展示:online_wechat 显示「待支付」+「去支付」(超过支付窗口则显示「支付已超时」并隐藏去支付,只保留改线下 / 取消),offline 显示「线下支付」。详情页保留「取消订单」(无删除按钮):待确认且未收款取消即删除;已确认/已收款提示「取消申请已提交」。详情页增加「切换支付方式」入口(仅待支付可改);支付按钮防抖 |
管理端(ui/wxapp_escort_admin):pages/order/orderDetail 需展示 refunding / refunded 与 payChannel,并新增「查询退款结果」按钮(调 POST /escort-record/:id/refund/query),用于退款回调丢失时的人工兜底;orderEdit 在存在未决流水时禁用金额输入。
七、关键技术点与易错点
- 金额换算:由
service.price字符串按小数点拆位直接得到整数分(不经过浮点);回调中校验amount.total与流水一致,防篡改 - openid 一致性:必须用发起支付小程序自身 appid 下的 openid(现有
user.app["wxapp-escort"].wxopenid满足);管理端小程序是另一个 appid,严禁串用 - 幂等与并发:
- 回调可能重复、乱序推送 → 以
outTradeNo/outRefundNo唯一索引 + 状态条件更新兜底 - 同订单重复请求支付 → prepay_id 未过期(2 小时内)复用原支付参数,不新建流水
- 同一订单的
createPayment串行执行(按 recordId 的进程内锁),防并发各建一条在途流水 - 需要新建流水时一律换新
outTradeNo;前端支付按钮防抖
- 回调可能重复、乱序推送 → 以
- 回调时效:验签后 5 秒内应答 200/204,业务处理放应答之后(或快速完成);应答失败微信将按 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h 重发至多 15 次
- 签名探测流量:微信会不定期发送
WECHATPAY/SIGNTEST/开头签名的探测请求,验签失败按规范应答 4XX/5XX +{"code":"FAIL"},不得当作攻击忽略或崩溃 - prepay_id 2 小时 / 支付窗口由
time_expire决定:prepay 有效期内重复点「去支付」直接复用;过期但仍在支付窗口内 → 沿用同一outTradeNo与原参数重新下单刷新 prepay(同一业务单不因重试换号)。支付窗口(time_expire)到期 → 关单、流水置closed,订单按失败终态处理。prepay 过期不等于交易单失效:不传time_expire时微信侧默认 7 天内仍可支付 - 调起支付签名与请求签名是两套:
paySign用appId/timeStamp/nonceStr/package四行签名串 + 商户私钥;appId必须与下单 appid 一致 - 服务器出网:health 服务需能访问
api.mch.weixin.qq.com;notify_url必须公网 HTTPS - Request-ID 日志:调微信接口时打印应答 HTTP 头
Request-ID,排障时提供给微信侧快速定位 - 支付方式切换与关单:用户从微信支付改为线下支付、或取消订单时,若已有未支付流水,必须调用关单接口。否则旧
prepay_id在 2 小时内仍可被支付,出现「已取消 / 已改线下却线上付了」的双重收款。关单失败不能只记日志:立即查单确认——已支付则中止切换并转退款,未确认则标closed_unconfirmed交对账 - 线下支付不改动现有履约链路:
payChannel=offline的订单仍是unpaid,平台收款后按现有管理端补记流程写入method+paidFee+paid,用户端不做支付动作 - 错误落库不能吞异常:支付/退款失败时先写
lastError再返回通用提示;若错误字段写库本身失败,必须logger.error兜底输出完整错误(含requestId),不能静默丢弃 - 错误信息脱敏:
lastError.message只存微信返回的message与系统错误原文,不写入请求报文、私钥、openid 等敏感内容;长度截断 500 字符 - 已取消订单收到支付:回调到达时订单可能已 cancelled。钱必须入账(流水落
pay_success),订单不能显示已收款,必须自动全额退款。这是「取消 + 关单失败 / 竞态」的必然残留,不能省;退款在应答之后异步发起,不占用 5 秒应答窗口 - 商户单号规则:同一业务单在同一支付窗口内只留一条在途流水;prepay 过期用原
outTradeNo重下,旧单已关单或支付窗口到期后才换新号(订单_id+ 递增序号)。已关闭的单号永不复用 - 改价与流水一致性:存在
created流水时禁止修改totalFee;金额变更必须先关单,否则微信侧金额与本地流水错位,对账无法核对 - 回调校验要全:除
out_trade_no与金额,还需校验解密报文中的mchid、appid、currency = CNY,防跨商户报文或异常报文混入 - 快照刷新失败:流水已
pay_success但订单快照刷失败时,必须logger.error记录,并依靠下一次回调 / 查单重刷(更新按状态条件幂等覆盖) - 退款幂等与兜底:
outRefundNo唯一索引捕获重复取消(返回「退款处理中」而非 500);退款调用超时/系统异常时先查退款确认是否受理,未受理用原单号原参数重试一次;退款回调丢失时用管理端「查询退款结果」补写终态 - 回调丢失必须由后台自己收敛:不能只靠用户回页面或管理端手动触发。巡检随服务启动默认运行,扫在途流水查单:
SUCCESS按回调同一套逻辑收敛,到期仍NOTPAY则关单
八、部署前检查清单
商户平台侧材料(缺一不可):
- JSAPI 支付权限已开通(商户平台 → 产品中心)
- 商户号与小程序 APPID 完成授权绑定(商户平台发起 + 公众平台确认,绑定后不可解绑)
- 商户 API 证书:
apiclient_cert.pem/apiclient_key.pem+ 证书序列号 - APIv3 密钥(32 位,账户中心 → API 安全)
- 微信支付公钥:
pub_key.pem+ 公钥 ID(PUB_KEY_ID_开头) - 商户号账户余额充足(退款从账户余额扣除,余额不足会直接退款失败)
合规(重要):
- 交易类小程序须按《交易类小程序运营规范》接入订单发货管理功能,否则可能被公众平台限制支付权限,正式环境调不起支付
服务器侧:
/etc/ehason/conf.json补wechatpay段;WXPAY_APIV3_KEY环境变量注入- 出网连通
api.mch.weixin.qq.com;api.huashengtec.comHTTPS 证书有效 - 防火墙/安全组放行微信支付回调 IP 段(支付回调与退款回调是不同 IP 段,均需放行 443 入站);有 WAF 时确认不拦截回调请求
九、验证与测试
- 本地自测:签名串构造自校验(官方签名生成/验证规范逐条比对);回调解密用官方示例报文验证;用项目自身的签名/验签/解密能力调
POST /v3/security/echo实测(读代码无法证明签名生效) - 沙箱/小额联调:1 分钱真实下单 → 支付 → 回调 → 查单 → 退款全链路
- 异常路径:中途取消支付、重复回调、prepay_id 过期重下(应沿用原单号)、支付后立即取消(自动退款)、回调延迟时的查单兜底、支付方式切换(微信→线下后旧 prepay 不可再支付)、支付按钮连续点击、并发发起支付(只产生一条在途流水)、支付窗口到期后关单、取消后用旧 prepay 完成支付(回调自动退款)、关单失败后切换(查单拦截已支付)、改线下再改回微信(新单号可正常支付)
- 失败落库验证:模拟网络不可达(错误码
NETWORK_ERROR)、模拟微信业务错误(如NO_AUTH)、模拟退款失败 → 检查payment_record/refund_record的lastError(含code/message/requestId)、errorCount、lastAttemptAt是否正确写入,且接口返回的是统一提示而非内部错误详情 - 资金安全专项:①取消待支付订单后用旧 prepay 完成支付 → 校验自动退款与
refund_record;②管理员对存在created流水的订单改价 → 应被拒绝;③同一订单多次发起支付 → 仅一条在途流水、仅一笔成功;④重复点击取消 → 返回「退款处理中」不报 500;⑤退款回调丢失 → 管理端查询补写终态;⑥金额为 0 的订单走微信 → 应被拒绝;⑦退款调用超时 → 自动查退款并原单号重试,不产生第二笔退款 - 兜底链路验证:①支付成功但人为让回调丢失 → 巡检在下一轮查单补单,订单转 paid;②回调验签失败 → 应答 4XX,随后由巡检收敛;③支付窗口到期未付 → 巡检查单为
NOTPAY后关单,流水置closed - 上线前按官方《接入质量检查清单》逐项核对
十、后续迭代项(本期不做)
- 下载交易账单/资金账单 API 的自动对账任务(字段已对齐,随时可加;本期经确认不做,由巡检查单 + 人工下载账单对账兜底)
- 巡检的多频率退避与告警(本期固定 10 分钟一轮,够用)
- 退款
ABNORMAL(用户银行卡作废/冻结)自动发起异常退款(本期转人工,资金停留在退款中间账户由财务处理) - 主备域名自动切换(本期只连主域名
api.mch.weixin.qq.com,接受单通道风险) - 部分退款 / 多次退款(本期一单一退,
outRefundNo固定-R1) - 培训报名(training_application)复用 payment_record 接入支付