开始集成

环境准备

在开始前，请您确保已完成 设置测试环境 步骤以便继续。

环境信息如下：

测试环境	https://p-gate-uat.checus.com/aggregate-pay/api/gateway/<PATH>
正式环境	https://pay-gate-hk-prod.checus.com/aggregate-pay/api/gateway/<PATH>

交互流程

用于支持用户按固定周期（如月度、季度、年度）自动支付。流程分为订阅计划配置、首次支付授权、后续周期扣款三个阶段：

阶段 1：订阅计划配置（商户侧）

• 创建订阅计划并定义金额、周期（如 30 天）、试用/优惠策略等
• 该计划将用于前端展示给用户选择

阶段 2：首次支付授权（用户侧）

• 商户调用 /subscriptionCreate 创建订阅实例
• Checus 返回 subscriptionNo
• 商户调用支付接口（收银台 / Drop-in / API）
• 用户完成首期支付 → Checus 激活订阅 → 状态变为 ACTIVE

阶段 3：后续周期扣款（系统自动）

• Checus 每个周期自动发起扣款，用户无需操作
• 商户接收扣款结果回调：
  • 成功→订阅计划状态维持 ACTIVE,订单扣款状态为 SUCCESS
  • 失败 → 该笔订单扣款状态为 FAILED
• 自动重试机制：
  • 最多重试 5 次（间隔 24h）
  • 自动扣款成功则该订阅计划状态依旧是 ACTIVE,5次扣款皆失败则更新为 TERMINATE 并通知商户

我们将以收银台模式例展示订阅支付整体流程

关键接口

关联交互时序	调用方向	接口地址/方式
创建订阅计划	商户 → Checus	/subscriptionCreate
激活订阅授权	商户 → Checus	/orderAndPay
发起首次授权付款	商户/前端 → Checus	前置组件或收银台
商户查询订阅状态	商户 → Checus	/subscriptionQuery
取消订阅计划	商户 → Checus	/subscriptionCancel

订阅支付集成步骤

创建订阅计划

商户可通过创建订阅计划接口发起订阅计划，Checus 支持多种类型订阅：普通订阅、n 天试用订阅和前 n 期优惠订阅。

1. 普通订阅

普通订阅指按设定周期进行扣款的标准订阅计划。

• 必填参数
  • subscriptionRequestId：商户创建订阅计划的唯一单号
  • userId：用户标识
  • callbackUrl：接收订阅结果和扣款结果的通知地址
  • subscriptionPlan：订阅计划信息，包括
    • subject：标题
    • description：描述，可选
    • totalPeriods：总期数
    • periodRule：扣款规则，包括
      • periodUnit：周期单位，按月（M）、日（D）、周（W）、年（Y）扣款
      • periodCount：周期间隔
    • periodAmount：每期扣款金额，包括金额和币种
    • firstPeriodStartDate：第一期扣款开始时间，要求与请求时间间隔小于 24 小时

2. n-天试用订阅

n 天试用订阅指在首期扣款前延迟 n 天，前 n 天为试用期，不扣款。

• 必填参数
  • 与普通订阅相同
  • firstPeriodStartDate：第一次扣款时间设为试用结束时间
• 说明
  • 在 firstPeriodStartDate 上设置延迟 n 天，表示试用期长度
  • 无需单独配置 trialPeriodConfig，默认首期扣款在试用结束时执行

3. 前 n 期优惠订阅

前 n 期优惠订阅指在订阅计划开始时，前若干期扣款金额为优惠或免费。

• 必填参数
  • 与普通订阅相同
  • firstPeriodStartDate：第一期扣款时间
  • trialPeriodConfig：前 n 期优惠配置，包括
    • trialPeriodCount：优惠期数
    • trialPeriodAmount：优惠金额及币种，可为 0 表示免费

返回内容示例：

• subscriptionNo：Checus 分配的订阅计划号
• subscriptionStatus：订阅计划状态，创建后通常为 INACTIVE，等待首期支付激活
• subscriptionRequestId：商户创建订阅计划的单号

商户收到成功响应后，即可等待订阅激活结果或周期扣款结果通知。

激活订阅计划

模式类型	启动方	说明	流程
前置组件激活	商户页面 + Checus收银台	在前置组件模式下，商户页面加载 Checus 前置组件，由组件完成卡信 息采集与支付流程，商户服务端需调 用两个接口完成激活： 1. 申请 Drop-in Session 2. 发起前置组件支付	用户在商户页面点击订阅 → 商户页面 加载 Checus 前置组件 → 完成首期支 付即完成激活
收银台激活	Checus收银台	在收银台模式下，商户服务器调用 支付创建接口 API 创建支付订单， 获取收银台地址后，商户页面跳转 至 Checus 收银台，由用户完成首笔 支付，支付成功后订阅计划即被激活。	用户在商户页面点击订阅 → 跳转 Checus 收银台 → 完成首期支付 即完成激活
API激活	商户服务器调用 Checus API	在 API 模式下，商户页面直接采集用 户卡信息，由商户服务器调用 API 支付/orderAndPay API 发起支付 并完成激活。支付过程中用户可能会跳 转到 3DS 验证页。	用户在商户页面点击订阅 → 商户 收银台 → 完成首期支付即完成激活

注意事项

• 激活请求必须携带 subscriptionNo，即创建订阅计划后 Checus 返回的订阅计划编号；
• 激活时的 currency 和 userId 必须与订阅计划中一致；
• 激活时的 subject 必须与订阅计划中一致；
• totalAmount 的规则：
  • 【n天试用】：激活金额为 0；
  • 【前n期优惠】：激活金额为优惠期金额；
  • 【普通订阅】：激活金额为每期固定扣款金额。

获取订阅计划状态结果

当订阅计划状态发生变更时，Checus 会向商户推送通知，状态可能包括激活成功、激活失败、订阅终止等。商户可以通过两种方式获取激活结果：回调通知或主动查询。

方式1. 订阅计划结果回调通知

当用户完成首期支付后，Checus 会通过回调接口（即在创建订单或订阅计划时上送的 notifyUrl）向商户发送支付结果通知，其中包含订阅激活状态。

• 回调地址配置方式
  • 接口传入：在创建订单或订阅计划时，通过 notifyUrl 参数上送，仅对当前订单生效
  • 平台设置：在商户管理平台配置全局回调地址，适用于所有订单
• 通知内容
  • subscriptionNo：订阅计划唯一标识
  • userId：用户标识
  • subscriptionStatus：订阅状态，包括激活成功（ACTIVE）、激活失败（ACTIVE_FAILED）、终止（TERMINATE）等
• 重试策略
  • 若未返回 HTTP 200，Checus 会在 24 小时内多次重试，重试间隔从立即、30秒、5分钟、10分钟、1小时到12小时

方式2. 主动查询订阅状态

若在设定时间内未收到激活结果通知，或订单状态不明确，商户可主动调用订阅状态查询接口获取状态。

• 接口名称：订阅状态查询
• 请求接口：/subscriptionQuery
• 请求参数：
  • subscriptionNo 或 subscriptionRequestId，两者必须传一个
• 返回内容
  • 订阅计划状态
  • 各期扣款状态及金额
  • 最新扣款结果及支付时间
  • 扣款失败时的错误码和原因

获取订阅计划状态变更结果

订阅计划激活后，商户可以通过回调或查询获取激活和扣款结果。

获取订阅计划激活结果

商户可通过创建订阅计划或激活订阅计划时上送的 notifyUrl 接收激活请求结果。

• 通知内容
  • status：激活请求状态，成功（SUCCESS）或失败（FAILED）
  • tradeToken：支付单号
  • totalAmount：激活总金额
  • completeTime：完成时间
  • paymentDetails：支付方式及卡信息

商户收到通知后应根据状态更新系统中的订阅计划状态。

获取首期扣款结果

普通订阅或前 n 期优惠订阅在激活时会进行首期扣款。扣款完成后，Checus 会通知商户：

• 通知内容
  • subscriptionNo：订阅计划号
  • subscriptionIndex：扣款期数
  • paymentStatus：扣款状态，成功（SUCCESS）或失败（FAILED）
  • payAmount：扣款金额及币种
  • paymentMethodType：支付方式
  • cardOrg：卡组织
  • tradeToken：支付单号，用于退款
  • payTime：支付时间
  • errorCode、errorMsg：扣款失败时提供错误信息

商户需返回 HTTP 200 确认接收通知。

后续周期性扣款

订阅计划激活后，Checus 会按照创建订阅计划时设置的提前扣款天数进行后续扣款，若未指定则按默认规则执行。

• 扣款结果通知与首期扣款相同，包括每期扣款期数、金额、状态、支付方式及失败原因
• 若某期扣款重试失败，Checus 会终止该订阅计划，并通知商户

管理订阅

订阅计划激活后，商户可进行管理操作，如查询扣款结果或取消订阅计划。

订阅状态变更通知

商户可通过创建订阅计划时上送的 callbackUrl 接收状态变更通知：

• 通知内容包含 subscriptionNo、subscriptionStatus 和 userId
• 状态包括激活、失败、终止、取消等

商户可根据状态更新系统并触发后续业务逻辑。

取消订阅计划

商户可取消订阅计划，若当前期正在扣款中，需等待该期完成后方可取消。

• 接口名称：取消订阅计划
• 请求方式：POST
• 请求参数：subscriptionNo：Checus 订阅计划号
• 请求接口：/subscriptionCancel
• 取消后状态：CANCEL

查询订阅扣款结果

商户可通过查询接口获取订阅计划各期扣款结果：

• 接口名称：订阅扣款结果查询
• 请求方式：POST
• 请求参数：subscriptionNo 或 subscriptionRequestId，两者必须传一个
• 请求接口：subscriptionQuery

返回内容：

• 各期扣款状态、金额、支付方式、支付时间
• 扣款失败原因及错误码