--- title: 场景与最佳实践 permalink: /notes/zh/integrate/subscription/best-practices/ createTime: '2026/07/15 16:30:00' nosearch: true llm: exclude: true description: '整理 Subscription 免费试用、套餐升级、周期末取消、字段保存、通知幂等和补偿查询等建议。' --- 本页整理常见订阅业务场景和商户侧实现建议。接入主流程请先阅读 [Subscription 集成方案](/notes/zh/integrate/subscription/integration/)。 ## 典型业务场景 ### 场景 1:7 天免费试用,到期后自动转正 适合会员试用、SaaS 新用户试用等场景。 建议做法: 1. 创建订阅时传 `trial.periodDays=7`;`trial` 只配置试用时间,不传金额或币种,正式计费价格放在 `flatPrice` 中。 2. 当收到 `status=IN_TRIAL` 且 `currentPeriod=0` 时,立即开通试用权益。 3. 试用期结束后,PingPong 自动发起首期正式扣款。 4. 若后续收到 `status=ACTIVE`,说明试用转正成功,继续提供正式服务。 5. 如果用户在试用期内取消订阅,PingPong 不再发起首个正式计费周期扣款。 6. 若试用转正失败并进入 `PAST_DUE`,按您的宽限期或补扣规则处理。 ### 场景 2:月付套餐升级,立即补差价 适合用户从基础版升级到高级版,且希望升级立即生效的场景。 建议做法: 1. 先调用 [预览订阅更新](/notes/zh/subscription/api/preview/),查看本次升级是否需要补扣及补扣金额。 2. 如果接受预估结果,再调用 [更新订阅](/notes/zh/subscription/api/update/),并设置适合的: - `effectiveMode=IMMEDIATE` - `billingAction=IMMEDIATE_CHARGE_AND_KEEP_CYCLE` 或其他业务需要的动作 3. 当收到 `notifyType=SUBSCRIPTION_PLAN_CHANGED` 通知后,更新本地套餐版本和权益(可用 `previousAttributes` 对比变更 diff)。 4. 若本次升级相关补扣为 `PENDING`,需等待支付或通知终态后再做最终权益确认。 5. 若订阅通过收银台创建,Update 响应返回 `action.paymentRedirectUrl` 时,需将买家重定向到该收银台地址完成补扣支付。 预览升级请求示例(仅展示 `bizContent`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "requestId": "REQ_SUB_PREVIEW_202607150001", "flatPrice": { "amount": "29.99", "currency": "USD" }, "period": { "unit": "MONTH", "count": 1 }, "totalPeriodCount": 12, "effectiveMode": "IMMEDIATE", "billingAction": "IMMEDIATE_CHARGE_AND_KEEP_CYCLE", "prorationMode": "PRORATED", "description": "Premium monthly membership" } ``` 更新订阅请求示例(仅展示 `bizContent`): ```json { "previewQuoteId": "SUPD-2607150312100000000900141522", "merchantSubscriptionId": "SUB_PLAN_202607150001", "requestId": "REQ_SUB_UPDATE_202607150001", "flatPrice": { "amount": "29.99", "currency": "USD" }, "goods": { "name": "Premium membership", "description": "Monthly membership service", "sku": "MEMBERSHIP-001", "unitPrice": "29.99", "number": "1", "imgUrl": "https://merchant.example.com/images/membership.png", "virtualProduct": "Y", "itemType": "3" }, "effectiveMode": "IMMEDIATE", "billingAction": "IMMEDIATE_CHARGE_AND_KEEP_CYCLE", "prorationMode": "PRORATED", "description": "Premium monthly membership" } ``` ### 场景 3:用户选择“本周期结束后取消” 适合用户希望关闭自动续费,但继续使用当前已付款周期服务的场景。 建议做法: 1. 先确认该订阅是否存在仍受 Update 门禁限制的计划变更;即使选择周期末取消,也不能绕过 Update 门禁。 2. 调用 [取消订阅](/notes/zh/subscription/api/cancel/),并传 `cancelAtPeriodEnd=true`。 3. Cancel 成功后,在本地记录“已计划取消”,但不要立即停服。同步响应通常仍为 `status=ACTIVE`,并返回未来的 `cancelAt`。 4. 在当前计费周期结束前,继续按原状态提供服务。 5. 等收到 `notifyType=SUBSCRIPTION_CANCELLED`(`status=CANCELLED`)的最终通知后,再停止续费与服务。 周期结束取消请求示例(仅展示 `bizContent`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "requestId": "REQ_SUB_CANCEL_202607150001", "cancelAtPeriodEnd": true } ``` 如果最终查询或通知返回如下结果,通常表示“当前周期已履约完成,订阅已真正结束”: ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-2607140720100000000500111522", "status": "CANCELLED", "cancelReason": "merchant_requested", "cancelAtPeriodEnd": true, "cancelAt": "1785159999000" } ``` ## 实施建议 为了让 Subscription 集成更稳,建议商户侧至少做好以下几件事: ### 1. 保存关键映射关系 建议本地至少保存以下字段: | 字段 | 用途 | |:---|:---| | `merchantSubscriptionId` | 商户侧订阅主键 | | `subscriptionId` | PingPong 订阅主键 | | `customerId` | 买家与订阅绑定关系(由创建买家接口获得) | | `status` | 当前订阅状态 | | `currentPeriod` | 当前周期序号;应结合 `status`、`trial` 和支付记录理解,不能单独据此判断试用期 | | `flatPrice.amount` / `flatPrice.currency` | 当前计划的正式计费金额和币种 | | `period.unit` / `period.count` | 单个正式计费周期配置 | | `totalPeriodCount` | 正式扣款总期数;不包含试用期 | | `trial` 相关字段 | 识别是否仍处于试用期 | | `autoRecovery.enabled` | 是否开启自动重试 | | 最近一次 `notifyType` / `updateAt` / `requestId` | 幂等和补偿处理 | ### 2. 把通知处理做成幂等 建议至少按以下维度做幂等: - 订阅通知:按 `subscriptionId + notifyType + updateAt` 或商户自身的幂等键处理。 - 支付通知:按支付通知自身的交易主键处理。 - 退款通知:按 `merchantRefundId` 或 `refundId` 做退款维度幂等。 - 同一订阅周期里,订阅通知、支付通知和退款通知要分开幂等,不要互相覆盖。 ### 3. 为补偿查询留兜底能力 即使已经接入通知,也建议保留主动查询逻辑: - 订阅创建后长时间未收到通知时,查 [查询订阅详情](/notes/zh/subscription/api/query/)。 - 想核对每期支付明细时,查 [查询订阅支付记录](/notes/zh/subscription/api/paymentsQuery/)。 - 发生计划变更后需要核对结果时,查订阅详情并对照本地套餐版本。 - 发生 Update 退款或 Cancel 退款后,需要核对退款终态时,查订阅支付记录并结合退款通知处理。 查询订阅详情响应示例(仅展示 `bizContent`): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "subscriptionId": "SUB-b7679cac22864072866fce3bf5ee6ba5", "requestId": "REQ_SUB_QUERY_202607150001", "status": "ACTIVE", "cancelReason": "", "currentPeriod": 1, "startAt": "1782711886000", "notifyUrl": "https://merchant.example.com/notify/subscription", "period": { "unit": "MONTH", "count": 1 }, "totalPeriodCount": 12, "autoRecovery": { "enabled": true }, "paymentRecords": [ { "period": 1, "merchantTransactionId": "SUB-b7679cac22864072866fce3bf5ee6ba5_P1" } ], "flatPrice": { "amount": "9.99", "currency": "USD" }, "goods": { "name": "Premium membership", "description": "Monthly membership service", "sku": "MEMBERSHIP-001", "unitPrice": "9.99", "number": "1", "imgUrl": "https://merchant.example.com/images/membership.png", "virtualProduct": "Y", "itemType": "3" } } ``` ### 4. 服务开通要以订阅状态为准 服务是否继续提供以订阅层状态为准,单笔支付和退款结果用于财务对账与异常补偿。三类结果的消费矩阵和幂等键定义见 [集成方案 · 步骤 3:获取订阅结果和支付结果](/notes/zh/integrate/subscription/integration/#步骤-3:获取订阅结果和支付结果)。