31 lines
2.0 KiB
Markdown
31 lines
2.0 KiB
Markdown
# 支付宝接入契约
|
||
|
||
## 元数据
|
||
|
||
- 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>
|
||
|
||
渠道版本、认证、字段、通知状态或重试语义变化时更新本文。
|