支付接入

Java 已提供微信、支付宝与 Stripe 的渠道适配，并保留人工支付。接入代码不携带客户商户材料；是否能实际收退款，取决于渠道资格、凭据、回调和目标环境验收。

渠道范围

渠道	发起结果	主要前置条件
WECHAT_NATIVE	qrCode	商户、证书与回调
WECHAT_JSAPI	payConfig	额外需要 buyerInfo.openid
WECHAT_H5	paymentUrl	额外需要 buyerInfo.clientIp
ALIPAY_PAGE / ALIPAY_WAP	paymentUrl	商户私钥、支付宝公钥与回调
STRIPE_PAYMENT_INTENT	clientSecret	密钥及后续客户端确认流程
STRIPE_CHECKOUT	paymentUrl	密钥、成功/取消地址与回调
MANUAL	hint	后台人工确认，不接受外部付款确认

在线渠道提供相应支付查询/关闭、退款/查询与回调处理；实际路径和字段以渠道配置页面、OpenAPI 和适配器为准。

当前微信不支持 sandboxMode=true，使用平台证书模式，不支持微信公钥 ID 模式。支付宝按配置切换沙箱；Stripe 使用测试或正式密钥决定环境，沙箱标记不会自动替换密钥。

接入前先跑通人工付款

先按 商城与库存 验证商品、仓库、订单和履约。然后选择一种实际要用的在线渠道，准备客户商户材料、HTTPS 回调地址与可用测试环境，不必同时配置所有平台。

下面的 YAML 只存放“加密商户凭据的密钥”；微信、支付宝、Stripe 的具体商户凭据在管理端支付渠道中填写。两者不能互相替代。

1. 准备凭据加密密钥

外置 YAML 设置 app.mall.payment.credential-key，值为 Base64 编码的 32 字节随机密钥。可在受控终端生成：

openssl rand -base64 32

只将生成值写入客户私有配置和受控备份，不放源码或普通日志。全部实例使用同一密钥，已经存储渠道凭据后不能直接换成新随机值。数据库中的凭据使用 AES-256-GCM 加密，丢失对应密钥无法正常解密。

未配置此密钥可使用人工付款，但不能保存第三方凭据。

2. 填写渠道配置

重启应用后，在支付渠道管理页面配置：

平台	credentials	metadata
微信	appId、mchId、serialNo、apiV3Key、privateKey	notifyUrlBase
支付宝	appId、privateKey、alipayPublicKey	notifyUrlBase、returnUrlBase
Stripe	secretKey、webhookSecret	currency、successUrlBase、cancelUrlBase

凭据按字段掩码回显。PATCH 中缺省或空字符串保留旧凭据，null 尝试清空，必填字段不能清空。存在历史交易的渠道不能物理删除。

3. 配置回调网关

notifyUrlBase 使用 https://客户域名/api/v1/mall/payment/webhook，适配器追加渠道编码，例如 /WECHAT_NATIVE。Stripe 成功/取消地址按配置原值使用。

网关保留原始请求体及验签头。回调路径免登录只是为了渠道投递，服务端仍需验签、校验身份与金额，并控制重复事件；不能向匿名回调提交自造成功结果确认付款。

4. 验证一条真实闭环

按当前渠道可用的测试环境先验证发起、付款、主动查询、通知、订单推进、退款及退款查询，确认重复回调不重复入账。再按客户发布流程验证正式配置。

连通性测试会真正调用 Provider；微信/Stripe 可能发起最小金额测试请求，不生成商城订单或流水、不自动确认付款。它不是无副作用的字符串格式检查，也不能代替完整交易验收。

验收时观察什么

操作	应确认的结果
发起支付	返回所选渠道要求的二维码、跳转地址或客户端确认参数
完成付款	主动查询或有效回调后，本地流水与订单状态一致
重复投递通知	不重复推进订单、不重复记账
发起退款	占用正确退款额度，查询/回调确认最终状态
退款后查询	渠道账单、本地退款流水和售后状态相符
网络超时	保留可查询的原流水，不误判为失败并再扣款

付款成功页的跳转只说明浏览器跳转完成，最终状态仍由服务端查询和验签后的通知确认。

超时和不确定状态

渠道网络调用在数据库事务外，本地结果通过幂等完成用例回写。创建超时、查询失败或关闭失败不等于未扣款，退款异常也不代表渠道未受理。

保留原 PENDING 流水和退款额度占用，通过查询或有效回调确认结果。在线流水不会仅因超过 60 分钟本地过期。持续未确认时按商户流水号核对渠道后台和账单，不能重复创建或人工批改为成功。

只有验签通过但处理失败的 Webhook 事件可在后台重试。历史失败/取消/过期流水必须逐笔对账，不能批量改回待支付。

开发与验证入口

源码位于 mall 的渠道配置、Provider、支付编排、退款及 Webhook 控制器/服务。随包 docs/guides/mall-payment-providers.md 给出精确范围，MallPaymentOrchestrationIT 等用于隔离协议和业务验证。

模拟平台 HTTP 与测试签名可以验证代码契约，不能替代实际商户、实际网络与资金结果验收。