即刻收直连模式接入指南

适用场景

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

直连模式当前面向白名单创作者开放，如果您有接入诉求，请留下您的信息： 创作者接入

支持的收费模式

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

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

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

接入准备

商户与支付宝的职责

开始前完成以下准备

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、支付宝搜索 即刻收 ，如未搜索到可扫码进入

2、配置商品

系统流程

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（查询商品收费能力和档位），biz_content 示例：

{
  "out_product_id": "np_d_f83a7c91"
}

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

收费状态与页面处理

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

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

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

买断和时长包

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（查询买断或时长访问决策），业务入参示例：

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

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

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

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

次数包和积分包

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

指定档位购买的 biz_content 示例：

{
  "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。

{
  "out_request_no": "consume_20260927_000001",
  "out_product_id": "np_d_f83a7c91",
  "external_buyer_id": "user_001",
  "amount": 1,
  "consume_reason": "生成一篇文章"
}

{
  "out_request_no": "consume_20260927_000001",
  "out_product_id": "np_d_f83a7c91",
  "external_buyer_id": "user_001"
}

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

应用应同时处理业务错误码和成功响应中的核销状态。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 列表。

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

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

{
  "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 只说明接口调用成功，业务是否允许访问或扣减是否成功，还需读取对应的业务状态。

幂等与重试

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

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

页面返回与通知

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

错误处理

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