# 支付宝接入契约

## 元数据

- 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>

渠道版本、认证、字段、通知状态或重试语义变化时更新本文。