支付宝开放平台接入 Skill
面向要接支付宝支付的开发者：先选对产品，再按正确姿势联调， 最后避开异步通知的经典大坑。
第一步：选对支付产品
| 产品 | 场景 | 用户操作 |
|---|---|---|
| 当面付 | 线下扫码（顾客扫店家/店家扫顾客） | 出示付款码或扫商家码 |
| APP 支付 | 自家原生 App 内 | 拉起支付宝 App |
| 手机网站支付 | 手机 H5 页面 | 跳支付宝 H5 或拉起 App |
| 电脑网站支付 | PC 网页 | 扫码或登录支付 |
| 小程序支付 | 支付宝小程序内 | 免跳转 |
| 周期扣款/预授权 | 订阅、押金 | 一次签约多次扣 |
选型速判：线下收银→当面付；App→APP支付；微信里的 H5 无法用支付宝，
要么引导浏览器打开要么换微信支付（见 weixin skill 支付章节）。
接入正确姿势
- 先沙箱后生产：开放平台控制台有独立沙箱环境（沙箱 AppID、 沙箱网关、沙箱版支付宝 App），联调全流程跑通再切生产参数
- 密钥体系（RSA2）：开发者生成应用私钥/公钥，公钥传平台换 支付宝公钥。记牢方向：请求用你的私钥签名，验回调用 支付宝公钥验签——两对密钥四把钥匙，混了必翻车
- 用官方 SDK：alipay-sdk 有 Java/PHP/Python/Node/Go 版， 签名/验签/加解密全封装，不要手写签名
- 接口协议：统一网关
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 典型用法
- 接入咨询：按业务场景给出产品选型 + 接入步骤清单 + 沙箱联调 计划
- 报错排查：贴报错码 → 按上表定位，优先检查密钥方向和签约状态
- 对账逻辑设计：指导用
alipay.data.dataservice.bill.downloadurl.query拉对账单，与本地订单做日对账 - 多渠道支付架构：与微信支付并存时的统一支付网关抽象建议
本 skill 不做什么
- 不涉及个人收款码规避签约的灰色玩法（违反协议，资金风险）
- 花呗分期、芝麻信用等产品需单独签约，准入门槛以官方为准
- 费率因行业/规模有差异（常见 0.38%-0.6% 区间），以签约页实际 展示为准，本文不报死数字
评论
加载中…