# 即刻收直连模式接入指南

## 适用场景

直连模式面向独立开发者、创作者或自行经营应用的商户。商户在支付宝管理小程序完成商品配置，应用服务端直接调用即刻收 OpenAPI，为应用用户提供托管购买、权益校验以及次数／积分核销能力。

直连模式当前面向白名单创作者开放，如果您有接入诉求，请留下您的信息：
[创作者接入](https://render.alipay.com/p/yuyan/180022670000179729/index.html?type=creator&source=aipay)

### 支持的收费模式

| 收费模式 | billing_mode | 权益或额度 | 应用使用方式 | 重复购买 |
| --- | --- | --- | --- | --- |
| 永久买断 | `ONE_TIME` | 永久使用权益 | 使用前查询访问决策 | 已有有效权益时不再购买 |
| 时长包 | `ONE_TIME_DURATION` | 固定有效期权益 | 使用前查询访问决策，可展示有效期 | 有效期内不续购；到期后按查询结果购买 |
| 次数包 | `QUANTITY`，`quota_unit=COUNT` | 可消耗次数 | 查询余额，每次服务按约定数量核销 | 可加购，新增额度累加 |
| 积分包 | `QUANTITY`，`quota_unit=POINT` | 可消耗积分 | 查询余额，按服务规则核销积分 | 可加购，新增额度累加 |

同一商品最终采用一种收费模式，该模式下可配置多个档位。例如，次数包可提供“20 次包”和“100 次包”，用户购买后增加相应次数。

时长包支持以下周期，按日历计算，不能将“一个月”固定换算成 30 天：

| duration_period | 对客名称 | 计算口径 |
| --- | --- | --- |
| `WEEK` | 一周 | 按日历增加 1 周 |
| `MONTH` | 一个月 | 按日历增加 1 个月 |
| `QUARTER` | 三个月 | 按日历增加 3 个月 |
| `YEAR` | 一年 | 按日历增加 1 年 |

本接入范围支持买断、固定周期时长包和次数／积分额度包，不包含自动续费、任意天数、有效期内时长续购或核销撤销。商品资料、价格与上下架以管理小程序支持的操作为准。

## 接入准备

### 商户与支付宝的职责

| 参与方 | 负责内容 |
| --- | --- |
| 商户／独立开发者 | 在管理小程序完成开通、商品资料、收费模式和档位配置，并管理商品上下架 |
| 应用服务端 | 使用商户的应用凭证签名调用 API；维护业务用户标识及消费记录；按权益和核销结果控制服务 |
| 应用客户端 | 展示商品、价格和余额；打开购买入口或展示二维码；页面返回后触发服务端查询 |
| 即刻收 | 提供托管购买页、支付与权益处理、权益查询和额度核销能力 |

### 开始前完成以下准备

1. 在管理小程序(支付宝搜索 **即刻收** ，或扫描集成流程中的小程序码进入)完成所需认证与签约，创建商品并配置收费模式、档位和价格；等待商品可售。
2. 在商品详情页复制商品 ID，作为接口入参 `out_product_id`。该 ID 由即刻收生成，必须使用本次调用商户名下的商品，不可自行编造。
3. 准备支付宝应用 `app_id`、应用私钥、对应支付宝公钥，完成所需接口权限与直连接入配置。应用调用身份应与商品所属商户一致；已获授权的第三方代理调用按授权规则传入 `app_auth_token`。
4. 应用服务端接入支付宝 SDK，配置签名和验签。网关为 `https://openapi.alipay.com/gateway.do`，版本为 `1.0`，使用 `RSA2`、`UTF-8` 和 JSON。
5. 为自身业务用户维护稳定的会员id标识，对应参数 `external_buyer_id`，保存购买入口请求和消费请求的业务上下文，支付前后及后续查询、核销必须保持一致。

## 手动集成

### 第一步：在管理小程序配置商品，查询可售状态

#### 商品配置
1、支付宝搜索 **即刻收** ，如未搜索到可扫码进入
::aipay-image{src="https://mass.alipay.com/aipay_assets/afts/file/ZKzqToivn50AAAAAQ4AAAAgAeoh5AQJr" width="100%"}

2、配置商品

::aipay-image{src="https://mass.alipay.com/aipay_assets/afts/file/3qkfQ5Zlg2AAAAAASHAAAAgAeoh5AQJr" width="100%"}

#### 系统流程

```mermaid
sequenceDiagram
    autonumber
    actor M as 商户
    participant C as 即刻收管理小程序
    participant N as 即刻收
    participant S as 应用服务端
    M->>C: 填写商品资料、收费方式和档位价格
    C->>N: 提交商品配置
    opt 需要完成开通
        C-->>M: 展示认证与签约步骤
        M->>C: 完成认证、签约
        C->>N: 继续处理商品申请
    end
    N->>N: 创建商品、审核与发布
    N-->>C: 商品状态、外部商品 ID
    M->>C: 进入商品详情，复制商品 ID
    M->>S: 配置 out_product_id
    S->>N: alipay.aipay.nowpaydirect.charge.query
    N-->>S: capability_status、billing_mode、charging_options
    S->>S: ENABLED 时展示新增购买入口
```

商户在小程序完成全部商品配置。直连模式不提供商品初始化、商品配置或商品启停 OpenAPI，开发者无需对接小程序内部接口。

调用 [alipay.aipay.nowpaydirect.charge.query（查询商品收费能力和档位）](api-list/alipay_aipay_nowpaydirect_charge_query.md)，`biz_content` 示例：

```json
{
  "out_product_id": "np_d_f83a7c91"
}
```

从响应读取实际 `billing_mode`、`quota_unit` 和 `charging_options`。同一商品采用一种收费模式，可在该模式下配置多个档位；价格由小程序配置，应用不通过购买接口传入价格。

#### 收费状态与页面处理

| capability_status | 商品含义 | 处理方式 |
| --- | --- | --- |
| `NOT_CONFIGURED` | 未找到收费配置 | 核对当前商户与商品 ID，在小程序完成配置 |
| `CONFIGURING` | 配置尚未完成 | 在小程序继续配置 |
| `PENDING` | 等待审核或发布 | 在小程序查看进度 |
| `ACTION_REQUIRED` | 需要商户处理 | 在小程序处理认证、签约或商品资料 |
| `ENABLED` | 允许新增购买 | 展示购买入口 |
| `DISABLED` | 停止新增购买 | 隐藏新购买入口；已有权益继续按权益接口判断 |
| `TERMINATED` | 商品已归档 | 不新增购买，在小程序查看状态 |

查询返回 `management_url` 时，可供商品所有者进入管理页；不要将管理地址作为用户购买入口。商品不可售时仍可能返回档位，不能只看档位列表非空就判定可以购买。

商品收费状态与用户权益状态分别判断。已下架不能直接推断已有权益失效；已上架也不意味着用户已获得权益。

### 第二步：按收费模式选择流程

| billing_mode | 使用前查询 | 需要购买时 | 支付页面返回后 | 实际消费时 |
| --- | --- | --- | --- | --- |
| `ONE_TIME` | alipay.aipay.nowpaydirect.purchase.consult | 使用 alipay.aipay.nowpaydirect.purchase.consult 返回的购买入口，或通过 alipay.aipay.nowpaydirect.purchase.create 选择指定档位 | 再查 alipay.aipay.nowpaydirect.purchase.consult | 按访问决策放行 |
| `ONE_TIME_DURATION` | alipay.aipay.nowpaydirect.purchase.consult | 同上 | 再查 alipay.aipay.nowpaydirect.purchase.consult，读取当前有效期 | 按访问决策放行 |
| `QUANTITY` | alipay.aipay.nowpaydirect.quota.query | alipay.aipay.nowpaydirect.purchase.create | 再查 alipay.aipay.nowpaydirect.quota.query | alipay.aipay.nowpaydirect.quota.verify；结果未知用 alipay.aipay.nowpaydirect.quota.refresh |

#### 买断和时长包

```mermaid
sequenceDiagram
    autonumber
    participant U as 用户
    participant P as 应用
    participant N as 即刻收 OpenAPI
    participant H as 支付宝托管购买页
    U->>P: 使用付费功能
    P->>N: alipay.aipay.nowpaydirect.purchase.consult
    N-->>P: decision
    alt ALLOW
        P-->>U: 开放服务
    else PURCHASE_REQUIRED
        P-->>U: 展示购买入口
        U->>H: 选择档位并支付
        H-->>P: 返回 callback_url
        P->>N: alipay.aipay.nowpaydirect.purchase.consult
        N-->>P: 最新 decision
        P-->>U: 按查询结果开放服务或提示刷新
    else DENY
        P-->>U: 不开放服务，按原因展示说明
    end
```

调用 [alipay.aipay.nowpaydirect.purchase.consult（查询买断或时长访问决策）](api-list/alipay_aipay_nowpaydirect_purchase_consult.md)，业务入参示例：

```json
{
  "out_product_id": "np_d_f83a7c91",
  "external_buyer_id": "user_001",
  "callback_url": "https://app.example.com/nowpay/purchase-return"
}
```

| decision | 应用操作 |
| --- | --- |
| `ALLOW` | 放行。时长包按返回的 `valid_from`、`valid_until` 展示有效期 |
| `PURCHASE_REQUIRED` | 使用返回的 `purchase_url` 或 `purchase_qr_code` 引导购买 |
| `DENY` | 不放行、不新建购买入口；根据 `reason_code` 展示说明或刷新 |

时长包权益区间为 `[valid_from, valid_until)`，在结束时间点失效。有效权益存在时，不引导用户重复购买。购买返回后仍需重新查询，只有新的 `decision=ALLOW` 才开放服务。

`purchase.consult` 不要求幂等请求号，多次查询可能产生不同购买入口；需要请求级幂等时使用 `purchase.create`。

若支付页面返回后权益暂未可用，可进行有限次查询并提示稍后刷新。不要因暂未查到权益而直接认定支付失败、自动再次支付或重复开放服务。

#### 次数包和积分包

```mermaid
sequenceDiagram
    autonumber
    participant U as 用户
    participant P as 应用
    participant N as 即刻收 OpenAPI
    participant H as 支付宝托管购买页
    P->>N: alipay.aipay.nowpaydirect.quota.query
    N-->>P: quota_unit / total / used / remaining
    P->>P: 按服务规则计算所需额度
    opt 额度不足或用户主动加购
        P->>N: alipay.aipay.nowpaydirect.purchase.create
        N-->>P: purchase_url / expire_time
        U->>H: 确认购买并支付
        H-->>P: 返回 callback_url
        P->>N: alipay.aipay.nowpaydirect.quota.query
        N-->>P: 最新余额
    end
    P->>P: 持久化消费请求号及业务参数
    Note over P,N: 应用按约定的服务交付时点发起正式核销
    P->>N: alipay.aipay.nowpaydirect.quota.verify
    N-->>P: 核销状态或业务错误
    opt 处理中、超时或结果未知
        P->>N: alipay.aipay.nowpaydirect.quota.refresh（原请求号）
        N-->>P: 核销结果
    end
    P->>P: 按最终结果更新消费和服务记录
```

1. 调用 [alipay.aipay.nowpaydirect.quota.query（查询次数或积分余额）](api-list/alipay_aipay_nowpaydirect_quota_query.md)，展示用户的可用余额。未购买时返回零余额，查询失败不按零余额处理。`remaining` 已排除预占，不能用 `total-used` 替代。
2. 应用按具体服务规则计算所需额度，例如生成一篇文章消耗 1 次，处理一次复杂任务消耗 10 积分。
3. 额度不足或用户主动加购时，调用 [alipay.aipay.nowpaydirect.purchase.create（获取购买链接）](api-list/alipay_aipay_nowpaydirect_purchase_create.md)。可传入查询得到的 `sku_id` 锁定档位，也可省略，让用户在购买页选择。
4. 用户返回后调用 `alipay.aipay.nowpaydirect.quota.query` 刷新余额。未到账时有限次刷新或提示稍后查询。
5. 在应用确定的服务交付时点，调用 [alipay.aipay.nowpaydirect.quota.verify（核销次数或积分）](api-list/alipay_aipay_nowpaydirect_quota_verify.md)。前置余额充足仍需正式核销，不能仅按余额查询结果执行本地扣减。
6. 对处理中或未知结果，使用原 `out_request_no` 调用 [alipay.aipay.nowpaydirect.quota.refresh（查询核销结果）](api-list/alipay_aipay_nowpaydirect_quota_refresh.md)，或用完全相同的原参数重试核销。

指定档位购买的 `biz_content` 示例：

```json
{
  "out_request_no": "purchase_20260927_000001",
  "out_product_id": "np_d_f83a7c91",
  "external_buyer_id": "user_001",
  "sku_id": "S0806000200863003",
  "callback_url": "https://app.example.com/nowpay/purchase-return"
}
```

`sku_id` 不指定时打开普通购买页。应用不传价格或价格版本参与创单；即刻收在用户确认购买时重新校验商品和档位。购买链接与二维码按不透明入口使用，不解析令牌，不自行拼接。

#### 额度核销与恢复示例

以下两组参数对应同一笔消费，查询必须使用核销时的原请求号。次数核销也必须显式传入 `amount=1`。

::::aipay-tabs{defaultActiveKey="核销额度"}
:::aipay-tab{key="核销额度" title="核销额度"}
```json
{
  "out_request_no": "consume_20260927_000001",
  "out_product_id": "np_d_f83a7c91",
  "external_buyer_id": "user_001",
  "amount": 1,
  "consume_reason": "生成一篇文章"
}
```
:::

:::aipay-tab{key="查询原核销结果" title="查询原核销结果"}
```json
{
  "out_request_no": "consume_20260927_000001",
  "out_product_id": "np_d_f83a7c91",
  "external_buyer_id": "user_001"
}
```
:::

::::

`consume_reason` 使用最长 256 字符的业务说明，应用自行持久化（当前代码限制严于预览文档的 512 字符）。不要填写完整提示词、用户隐私、业务 JSON 等内容，也不要依赖查询结果回传该字段恢复原业务上下文。

| 核销结果 | 是否确认扣减 | 应用处理 |
| --- | --- | --- |
| `code=10000` 且 `consume_status=SUCCEEDED` | 是 | 保存核销流水、实扣量及结果，按业务约定完成服务记录 |
| `code=10000` 且 `consume_status=FAILED` | 否 | 按原因处理；余额不足引导补充额度 |
| `code=10000` 且 `consume_status=PROCESSING` | 待确认 | 使用原请求号查询，避免并发重扣 |
| `NOW_PAY_QUOTA_INSUFFICIENT` | 本次请求未确认成功 | 处理余额不足，不将网关失败忽略为正常成功 |
| 网络超时、系统错误或未知状态 | 待确认 | 保存原请求，查询或原参数重试 |
| 核销记录不存在 | 待确认 | 核对请求号与商品，继续查询或原参数重试；不换号重扣 |

应用应同时处理业务错误码和成功响应中的核销状态。`PROCESSING` 时 `consumed`、`remaining` 可能缺失，不能补零后推断结果。`remaining` 仅在成功扣减时用作该笔扣减后的余额；结果查询返回的是原核销结果，需要实时余额时调用 `alipay.aipay.nowpaydirect.quota.query`。

核销与应用自身服务交付是两个动作。应用须根据业务明确先核销还是先交付，并对服务执行、超时恢复、交付失败处理做一致设计。当前能力不提供核销成功后的自动返还，不应将核销当作可自动释放的预占。应用服务端应记录并校验消费记录的用户归属，结果查询使用原消费记录中的参数。

### 第三步：在管理小程序维护商品

商户在管理小程序查看审核进度、处理资料和管理上下架。操作后调用 `alipay.aipay.nowpaydirect.charge.query` 刷新应用中的商品状态。

下架停止新增购买，原有买断、时长包或额度权益仍按对应接口结果处理；下架操作不等同于退款或回收权益。

## 请求与响应处理

### 服务端调用

业务参数序列化为 JSON 后放入 `biz_content`，与 `app_id`、`method`、`charset`、`sign_type`、`timestamp`、`version` 等公共参数一起签名提交。每份 API 文档均提供 Java 和 cURL 示例，参见 [API 列表](api-list.md)。

所有接口返回 JSON 业务结果，再由应用打开结果里的页面链接。接口调用使用服务端 SDK 的普通执行方法，如 Java 的 `execute`。不要将这些接口作为直接输出 HTML 支付表单的页面支付接口使用。

以额度查询为例，响应封装如下：

```json
{
  "alipay_aipay_nowpaydirect_quota_query_response": {
    "code": "10000",
    "msg": "Success",
    "quota_unit": "COUNT",
    "total": 20,
    "used": 0,
    "remaining": 20,
    "as_of_time": "2026-09-27 10:00:00"
  },
  "sign": "RESPONSE_SIGNATURE_PLACEHOLDER"
}
```

上例仅说明响应结构，签名不是有效签名。应用先验签、再判断 `code`；`code=10000` 只说明接口调用成功，业务是否允许访问或扣减是否成功，还需读取对应的业务状态。

### 幂等与重试

| 操作 | 应用应保存的定位信息 | 重试原则 |
| --- | --- | --- |
| alipay.aipay.nowpaydirect.purchase.create | 独立购买入口请求号及完整业务参数 | 默认有效期为 30 分钟 |
| alipay.aipay.nowpaydirect.quota.verify | 消费请求号、商品、受益人、amount、consume_reason | 使用原请求号和原参数重试，或查询原核销结果 |
| alipay.aipay.nowpaydirect.quota.refresh | 原消费请求的定位信息 | 只查询原核销记录，不生成新的核销号 |

商户应保证 `out_request_no` 在其业务范围内唯一，不跨商品、用户或不同消费复用。

对可恢复异常采用有限次数、带间隔的查询或重试；超过应用预设等待时间后保留“待确认”状态，由后续查询或排查恢复。不要因达到等待上限就将未知结果强制判为失败。

### 页面返回与通知

`callback_url` 仅用于用户操作结束后的页面跳转。买断与时长包在返回后查询 `alipay.aipay.nowpaydirect.purchase.consult`，额度包查询 `alipay.aipay.nowpaydirect.quota.query`，小程序商品管理操作后查询 `alipay.aipay.nowpaydirect.charge.query`。

### 错误处理

1. 网关或签名错误：按[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)排查公共参数、应用权限和验签配置。
2. 参数、商品或模式错误：按具体 API 的 `sub_code` 核对业务参数及商品配置；不依赖 `sub_msg` 的展示文案编写业务分支。
3. 核销余额不足：兼容 `NOW_PAY_QUOTA_INSUFFICIENT` 业务错误及 `FAILED` 的结果表达，不确认消费成功。
4. 幂等冲突：读取应用已保存的原请求进行核对；不能通过替换请求号掩盖一笔未确认的消费。
5. 核销未找到记录或依赖异常：保留原请求号，继续查询或原参数重试。