Zhifubao

支付宝开放平台接入指南。Use for: (1) 选对支付产品——当面付/APP支付/手机网站/电脑网站/小程序支付的适用场景与费率结构, (2) 沙箱联调、RSA2 签名与异步通知验签的正确姿势, (3) 高频报错排查（ISV权限不足/签名错误/回调不来）。Alipay Open Platform integration guide: payment-product selection, sandbox testing, RSA2 signing, and async-notification pitfalls.

支付宝开放平台接入 Skill

面向要接支付宝支付的开发者：先选对产品，再按正确姿势联调， 最后避开异步通知的经典大坑。

第一步：选对支付产品

产品	场景	用户操作
当面付	线下扫码（顾客扫店家/店家扫顾客）	出示付款码或扫商家码
APP 支付	自家原生 App 内	拉起支付宝 App
手机网站支付	手机 H5 页面	跳支付宝 H5 或拉起 App
电脑网站支付	PC 网页	扫码或登录支付
小程序支付	支付宝小程序内	免跳转
周期扣款/预授权	订阅、押金	一次签约多次扣

选型速判：线下收银→当面付；App→APP支付；微信里的 H5 无法用支付宝， 要么引导浏览器打开要么换微信支付（见 weixin skill 支付章节）。

接入正确姿势

1. 先沙箱后生产：开放平台控制台有独立沙箱环境（沙箱 AppID、 沙箱网关、沙箱版支付宝 App），联调全流程跑通再切生产参数
2. 密钥体系（RSA2）：开发者生成应用私钥/公钥，公钥传平台换 支付宝公钥。记牢方向：请求用你的私钥签名，验回调用 支付宝公钥验签——两对密钥四把钥匙，混了必翻车
3. 用官方 SDK：alipay-sdk 有 Java/PHP/Python/Node/Go 版， 签名/验签/加解密全封装，不要手写签名
4. 接口协议：统一网关 openapi.alipay.com/gateway.do， method 参数区分接口（如 alipay.trade.precreate 当面付预下单、 alipay.trade.page.pay 电脑网站支付），参数以官方文档为准

异步通知（notify）经典大坑

• 回调处理完必须回写纯字符串 success（不是 JSON），否则支付宝 会按 4m/10m/…间隔重发 8 次，你会看到"重复回调"
• 必须验签 + 幂等：验支付宝公钥签名防伪造，按 out_trade_no 幂等防重复入账
• 本地开发收不到回调是正常的（公网不可达），用内网穿透或沙箱 轮询查单（alipay.trade.query）兜底
• 金额校验：回调里的 total_amount 要和你订单金额比对，防篡改

高频报错排查

报错	根因	处理
ISV 权限不足 (isv.insufficient-isv-permissions)	产品没签约或没绑定到该 App	控制台确认产品状态"已生效"
签名错误 (invalid-signature)	密钥对不匹配/字符集不一致/参数拼接错	用 SDK；检查是否误用沙箱密钥打生产
系统繁忙 (aop.ACQ.SYSTEM_ERROR)	偶发	用 trade.query 查单确认状态再决定重试
回调收不到	notify_url 非公网 HTTPS / 返回了非 success	见上节

Agent 典型用法

1. 接入咨询：按业务场景给出产品选型 + 接入步骤清单 + 沙箱联调 计划
2. 报错排查：贴报错码 → 按上表定位，优先检查密钥方向和签约状态
3. 对账逻辑设计：指导用 alipay.data.dataservice.bill.downloadurl.query 拉对账单，与本地订单做日对账
4. 多渠道支付架构：与微信支付并存时的统一支付网关抽象建议

本 skill 不做什么

• 不涉及个人收款码规避签约的灰色玩法（违反协议，资金风险）
• 花呗分期、芝麻信用等产品需单独签约，准入门槛以官方为准
• 费率因行业/规模有差异（常见 0.38%-0.6% 区间），以签约页实际 展示为准，本文不报死数字