2.0 KiB
支付宝接入契约
元数据
- Owner：支付适配维护人
- 实现：
pkg/alipay/，github.com/smartwalle/alipay/v3 v3.2.29 - 核验日期：2026-08-07
- 环境：支付宝沙箱或生产商户；本文不保存凭证
当前实际使用范围
系统使用手机网站支付 TradeWapPay 生成签名支付 URL，并处理异步通知；未发现退款、转账或当面付调用。payment.PaymentNo 写入 out_trade_no，金额从分转为元字符串，产品码固定为 QUICK_WAP_WAY，有效期存在且晚于当前时间时写入 time_expire。
配置、认证与关键字段
配置来自支付配置记录：AppID、应用私钥、支付宝公钥、通知地址和返回地址。SDK 使用 RSA2 完成请求签名与通知验签。请求关键字段为 notify_url、return_url、subject、out_trade_no、total_amount、product_code、time_expire。
通知只有 trade_status=TRADE_SUCCESS 或 TRADE_FINISHED 才进入成功处理；处理前还需匹配商户支付号、配置和金额。业务支付号承担幂等标识，重复通知由现有支付状态条件保护。
失败、超时与重试
配置不完整或 SDK 生成 URL 失败映射为项目支付配置错误；通知签名、金额或状态不符按回调失败处理。创建支付 URL 不自动重试，避免重复业务意图；通知是否重发由支付宝控制，本系统必须保持回调幂等。SDK 超时未在本适配器单独覆盖。
安全与验证
私钥、公钥原文、完整通知报文和用户标识不得写入本文或普通日志。可复现静态证据：pkg/alipay/wap.go、pkg/alipay/notify.go、internal/handler/callback/payment.go。真实验收需在隔离商户完成下单、签名通知、错误金额和重复通知四个场景；本次 Context 重建不调用真实渠道。
官方参考：https://opendocs.alipay.com/open/203/107091
渠道版本、认证、字段、通知状态或重试语义变化时更新本文。