Alipay Payment Integration

---
name: alipay-payment-integration
description: >-
  支付宝开放平台支付产品接入最佳实践。涵盖当面付、订单码支付、App支付、
  JSAPI支付、手机网站支付、电脑网站支付、预授权支付、商家扣款等全场景产品选型与集成指导。
  当用户提到"接入支付宝"、"集成支付宝支付"、"对接支付"、"支付宝收款"、
  "加个支付功能"、"支付宝下单"、"H5支付"、"小程序支付"、"预授权"、
  "付款码"、"扫码支付"、"网页支付"、"PC支付"、"周期扣款"、"自动续费"、
  "会员订阅"、"连续包月"、"代扣"时使用此 Skill。

---

所有支付宝支付产品的文档均为在线动态链接，接入前务必先阅读对应产品的在线文档获取最新接口参数和代码示例。

## 文档访问规范

访问支付宝在线文档时，直接使用 curl 获取内容：

```bash
# 示例：获取当面付文档
curl -sL "https://ideservice.alipay.com/cms/site/0izcu3"
```

### 递归访问

文档页面内包含的链接需要递归访问以获取完整内容。访问流程：

1. 首先访问主文档 URL
2. 解析文档中的链接（产品介绍、接入准备、接口文档等）
3. 递归访问这些链接获取详细内容

```bash
# 访问当面付子链接示例
curl -sL "https://ideservice.alipay.com/cms/site/0izal0"   # 产品介绍
curl -sL "https://ideservice.alipay.com/cms/site/0izal1"   # 接入准备
```
## 集成流程约束

### 步骤1. 集成信息收集

接入前根据用户输入必须阅读下列文档：
- **SDK选择**：根据开发语言选择通用版或Easy版SDK来进行集成。[下载地址](https://ideservice.alipay.com/cms/site/0j0cjj)
- **加签方式**：签名支持 RSA 和 RSA2，推荐使用 RSA2（SHA256WithRSA）。[加签说明](https://ideservice.alipay.com/cms/site/02mriz)

### 步骤2. 获取产品集成文档

- **根据路由到的产品文档获取完整集成信息**：必须阅读快速接入、完整的接口文档列表、异步通知说明、注意事项等。根据用户输入和接入诉求尽可能多的收集信息，使用curl指令访问文档。

- **必须阅读接入规范与常见陷阱**：[接入规范](https://ideservice.alipay.com/cms/site/0j0kl2)

- **公共错误码说明**：此处为公共错误码说明，开发者在接入过程中遇到其他报错信息，可以参考所调用接口的 API 文档的 **业务错误码** 部分。[错误码说明](https://ideservice.alipay.com/cms/site/02km9f)

### 步骤3. 集成校验

在集成过程中及发布上线前进行校验，确保签名验签、异步通知、异常处理等符合规范。校验结果供参考，开发者务必按照支付宝最新开放平台文档进行检查。详见：[集成校验清单](references/checklist.md)

## 接入路由表

根据用户的业务场景，路由到对应的产品文档：

| 场景 | 推荐产品 | 核心 API | 在线文档 |
| --- | --- | --- | --- |
| 线下门店，用户出示付款码，商家扫码枪扫码收款 | 当面付 | `alipay.trade.pay` | [当面付文档](https://ideservice.alipay.com/cms/site/0izcu3) |
| 商家生成二维码，用户打开支付宝扫码付款 | 订单码支付 | `alipay.trade.precreate` | [订单码支付文档](https://ideservice.alipay.com/cms/site/0izg0z) |
| 手机浏览器 H5 页面内唤起支付宝付款 | 手机网站支付 | `alipay.trade.wap.pay` | [手机网站支付文档](https://ideservice.alipay.com/cms/site/0izne3) |
| 电脑浏览器网页内跳转支付宝收银台 | 电脑网站支付 | `alipay.trade.page.pay` | [电脑网站支付文档](https://ideservice.alipay.com/cms/site/0iztfv) |
| 支付宝小程序内调起支付 | JSAPI 支付 | `alipay.trade.create` + `my.tradePay` | [JSAPI 支付文档](https://ideservice.alipay.com/cms/site/0izg0f) |
| 原生 iOS/Android/鸿蒙 App 内调起支付宝付款 | App 支付 | `alipay.trade.app.pay` | [App 支付文档](https://ideservice.alipay.com/cms/site/0izsn4) |
| 押金冻结、信用住、免押租赁 | 预授权支付 | `alipay.fund.auth.order.app.freeze` | [预授权支付文档](https://ideservice.alipay.com/cms/site/0j0lyx) |
| 周期扣款、自动续费、会员订阅、连续包月 | 商家扣款 | `alipay.trade.app.pay`（支付并签约）+ `alipay.trade.pay`（后续扣款） | [商家扣款文档](https://ideservice.alipay.com/cms/site/0j0g6k) |

回答任何接入问题或编写代码前，先通过 curl 阅读上表中对应的在线文档链接。文档内包含最新的接口参数、代码示例和注意事项。

## 快速决策树

```
用户咨询支付宝接入
        |
        +-- 线下门店收款？
        |       +-- 用户出示付款码，商家扫 --> 当面付
        |       +-- 商家出示二维码，用户扫 --> 订单码支付
        |
        +-- 线上支付？
        |       +-- 原生 App（iOS/Android/鸿蒙）--> App 支付
        |       +-- 支付宝小程序 --> JSAPI支付
        |       +-- 手机浏览器 H5 --> 手机网站支付
        |       +-- 电脑浏览器网页 --> 电脑网站支付
        |
        +-- 需要冻结资金/押金？
        |       +-- 预授权支付
        |
        +-- 周期性自动扣款？
                +-- 会员订阅/连续包月/自动续费 --> 商家扣款
```

## 场景关键词匹配

| 关键词 | 路由产品 |
| --- | --- |
| 付款码、条码支付、扫码枪、被扫、线下门店、便利店、商超、餐饮、收银台扫码、实体店、面对面收款、扫码枪收款、用户出示付款码 | 当面付 |
| 订单码、商家二维码、主扫、预下单、商家生成二维码、用户扫码支付、商品二维码、预创建订单 | 订单码支付 |
| H5支付、WAP支付、手机网站、手机浏览器、移动端网页、手机网页支付、wap收银台、手机端网页、移动H5 | 手机网站支付 |
| PC支付、电脑网站、网页支付、电脑端支付、PC网页、电脑浏览器、网站支付、传统网页支付、网页收银台 | 电脑网站支付 |
| 小程序支付、JSAPI、支付宝小程序、生活号、小程序内支付、小程序收银台、小程序JSAPI、my.tradePay、小程序下单、支付宝内小程序 | JSAPI 支付 |
| App支付、移动应用支付、iOS支付、Android支付、鸿蒙支付、App内支付、原生App支付、手机App支付、移动端App、SDK支付、客户端支付 | App 支付 |
| 预授权、押金、资金冻结、信用住、免押、先享后付、酒店押金、租车押金、充电宝押金、单车押金、民宿押金、冻结资金、授权冻结、押金退还 | 预授权支付 |
| 周期扣款、自动续费、会员订阅、连续包月、代扣、商家扣款、定期扣款、会员自动续费、包月会员、订阅制、定期扣费、委托扣款、协议扣款 | 商家扣款 |

## 澄清话术

当用户描述模糊时：

```
请确认您的业务场景：

1. 线下门店收款
   - 当面付：用户出示付款码，商家用扫码枪收款
     适用：便利店、商超综合体、餐饮店、医院、学校、电影院、旅游景区等实体门店
   - 订单码支付：商家生成二维码，用户扫码付款
     适用：商品售卖、媒体广告支付等场景

2. 线上App支付
   - 原生 iOS/Android/鸿蒙 App 内调起支付宝付款
   - App 未安装支付宝客户端时可降级 H5 支付

3. 支付宝小程序支付
   - JSAPI支付：小程序内调起支付宝收银台完成支付
   - 适用：支付宝小程序内购物、服务购买等场景

4. 手机网站支付
   - 手机浏览器 H5 页面内唤起支付宝 App 或网页收银台
   - 适用：移动端网页内支付等场景

5. 电脑网站支付
   - 电脑浏览器跳转支付宝网页收银台
   - 支持扫码支付或登录账户支付
   - 适用：PC端电商网站、在线服务平台等

6. 预授权支付
   - 先冻结资金或信用额度，按实际消费扣款，剩余解冻归还
   - 适用：酒店民宿、传统租车、分时租赁、单车租赁、充电宝、雨伞、3C数码/手机/相机租赁等

7. 商家扣款（周期自动扣款）
   - 用户签约授权后，商家主动发起周期性扣款
   - 适用：会员包月、自动续费、定期还款等

请描述您的具体业务需求？
```

## 安全红线

> ⛔ 以下规则为支付宝支付接入的**安全红线**，违反可能导致资金损失或安全事故，必须严格遵守。提示用户需要在上线前按照[集成校验清单](references/checklist.md)及支付宝开放平台文档进行校验

- **私钥禁止存客户端**：构造交易数据并签名必须在商家服务端完成，私钥绝对不能保存在商家APP客户端中。
- **私钥禁止记日志**：私钥不得出现在任何日志中。
- **私钥禁止传公共仓库**：私钥不得上传到GitHub、GitLab等公共代码仓库。
- **前台支付结果不可信**：前台同步跳转结果不可信，必须以支付宝异步通知或调用交易查询接口获取结果为准。
- **未确认不重付**：在未确认支付结果前，不能要求用户再次付款，必须先通过异步通知或查询接口确认支付结果。
- **异步通知必须先验签**：收到异步通知后必须先验签，确保通知来自支付宝。

---

## 接入环境说明

- **沙箱环境**：地址：https://openapi-sandbox.dl.alipaydev.com/gateway.do。[沙箱环境说明](https://ideservice.alipay.com/cms/site/02np8i)
- **正式环境**：地址：https://openapi.alipay.com/gateway.do

## 注意事项

- 本 Skill **不支持商家分账产品接入**，分账需求请查阅开放平台文档或咨询支付宝技术支持。
- 业务咨询和接入问题请查阅 [开放平台在线文档](https://open.alipay.com/) 或咨询支付宝技术支持。
- 商家扣款产品已于2026年4月2日完成产品升级，本文仅支持最新版本的接入。原有曾使用旧版本接入的商家仍可继续使用，但后续将不再进行能力更新，也不再接受新场景接入，相关文档前往[开放平台在线文档](https://open.alipay.com/) 查看。
- 商家扣款当前只支持周期性扣款模式，用户主动免密支付场景暂不支持接入。
- 测试阶段建议开发者优先使用沙箱环境。
- 本文档中所有链接均指向支付宝在线文档，内容会动态更新，编写代码前务必阅读最新版本。