跳到主要内容

订阅接入流程

订阅是指商户先在管理后台创建并上链订阅方案，再通过接口为用户生成订阅链接。用户在订阅页面完成签约和授权后，商户可以按周期主动发起扣款，并通过回调通知或查询接口同步订阅状态。

1. 订阅开通流程​

订阅开通过程的接口调用时序图如下：

调用流程如下：

  1. 管理员先在管理后台创建订阅方案，并完成多签审批。审批通过后，订阅方案才会真正上链生效，商户需要记录对应的 planId。
  2. 商户系统调用 /subscribe/payment/create（创建订阅链接接口）向 UtcPay 发起订阅请求，UtcPay 对请求参数进行校验后，返回订阅 ID、订阅页面路径 paymentUrl 和链接过期时间。
  3. 商户系统需要将 paymentUrl 与官方域名拼接后再引导用户访问订阅页面。用户在页面中完成钱包连接、签约确认和授权扣款额度。
  4. 订阅相关事件触发后，UtcPay 会通过 POST 请求 notifyUrl（订阅时商户入参传入）发送回调通知。商户需要根据回调中的 subscriptionType 区分签约、授权、扣费和退订等不同事件。
  5. 商户也可以调用 /subscribe/list（查询订阅列表接口）查询订阅状态，不必只依赖前端跳转结果。
注意
  • 接口返回的 paymentUrl 是相对路径，必须拼接 UtcPay 官方域名后才能访问：正式环境为 https://payment.utcpay.com，沙盒环境为 https://payment-sandbox.utcpay.com。
  • 商家系统接收到回调通知以后，必须通过验签（验证通知请求头中的 X-PAY-SIGN 参数）来确保订阅通知是由 UtcPay 发送的。详细验签规则可查看回调通知验签。
  • 接收到回调通知并验签通过后，请务必核对通知中的订阅 ID、方案 ID、用户标识等参数，并根据 subscriptionType 和业务状态字段进行后续处理。
  • 用户完成页面跳转不等于订阅已经生效。商户应以 SubscriptionApprove 回调或查询接口返回的订阅状态为准。

2. 周期扣费流程​

用户完成授权后，商户需要主动发起周期扣费。周期扣费过程的接口调用时序图如下：

调用流程如下：

  1. 商户系统调用 /subscribe/chargeable/list（查询待扣款订阅列表接口）获取当前需要扣款的订阅列表。返回结果中包含 subscriptionId、userHash、nextPayTime 等字段，可作为签名和对账依据。
  2. 商户将待扣款订阅数据提交给安全签名机接口，由签名机完成签名并自动广播交易。EVM 链请使用签名 EVM 订阅扣款接口，TVM 链请使用签名 TVM 订阅扣款接口。
  3. 扣款成功或失败后，UtcPay 会通过订阅回调发送 subscriptionType=SubscriptionBilling 的通知，商户可据此更新订阅有效期、服务状态或失败补偿流程。
  4. 商户也可以调用 /subscribe/list 查询订阅当前状态，或再次调用 /subscribe/chargeable/list 确认该订阅是否仍在待扣款列表中。
注意
  • 周期扣费依赖安全签名机，商户需要预先完成签名机部署。部署说明可参考安全签名机接口说明。
  • 调用签名机时，subscriptionIds 和 userHashs 必须一一对应，否则会导致签名或扣款失败。
  • 请优先处理查询接口返回中 isChargeableCurrentCycle=0 的订阅记录；若返回值表示当前周期不可扣费，则不应继续发起本期扣款。
  • 即使签名机接口已经返回结果，商户仍应以 SubscriptionBilling 回调或查询到的最终状态作为业务入账依据。

3. 退订流程​

当用户需要取消后续订阅时，商户可以创建退订链接，引导用户在链上取消授权。退订过程的接口调用时序图如下：

调用流程如下：

  1. 用户需要取消订阅时，商户系统调用 /subscribe/cancel/create（创建退订链接接口）向 UtcPay 发起退订请求。
  2. UtcPay 校验请求参数后，返回退订页面路径 paymentUrl 和链接过期时间。商户需要将 paymentUrl 与官方域名拼接后再提供给用户访问。
  3. 用户进入退订页面后，通过钱包确认取消授权。退订完成后，系统会异步发送 SubscriptionCancel 回调通知。
  4. 商户也可以调用 /subscribe/list 查询订阅状态，确认该订阅是否已经进入取消授权或终止状态。
注意
  • 退订链接的访问规则与订阅链接一致，必须拼接官方域名后使用，不能直接使用接口返回的相对路径。
  • 商家系统接收到 SubscriptionCancel 回调后，同样需要先验签，再更新本地订阅状态，停止后续自动扣费或服务发放。
  • 用户退订后，商户仍应通过查询接口或回调结果确认订阅状态，避免继续对已取消授权的用户发起扣款。
最后于 更新