场景与最佳实践
本页整理常见订阅业务场景和商户侧实现建议。接入主流程请先阅读 Subscription 集成方案。
典型业务场景
场景 1:7 天免费试用,到期后自动转正
适合会员试用、SaaS 新用户试用等场景。
建议做法:
- 创建订阅时传
trial.periodDays=7;trial只配置试用时间,不传金额或币种,正式计费价格放在flatPrice中。 - 当收到
status=IN_TRIAL且currentPeriod=0时,立即开通试用权益。 - 试用期结束后,PingPong 自动发起首期正式扣款。
- 若后续收到
status=ACTIVE,说明试用转正成功,继续提供正式服务。 - 如果用户在试用期内取消订阅,PingPong 不再发起首个正式计费周期扣款。
- 若试用转正失败并进入
PAST_DUE,按您的宽限期或补扣规则处理。
场景 2:月付套餐升级,立即补差价
适合用户从基础版升级到高级版,且希望升级立即生效的场景。
建议做法:
- 先调用 预览订阅更新,查看本次升级是否需要补扣及补扣金额。
- 如果接受预估结果,再调用 更新订阅,并设置适合的:
effectiveMode=IMMEDIATEbillingAction=IMMEDIATE_CHARGE_AND_KEEP_CYCLE或其他业务需要的动作
- 当收到
notifyType=SUBSCRIPTION_PLAN_CHANGED通知后,更新本地套餐版本和权益(可用previousAttributes对比变更 diff)。 - 若本次升级相关补扣为
PENDING,需等待支付或通知终态后再做最终权益确认。 - 若订阅通过收银台创建,Update 响应返回
action.paymentRedirectUrl时,需将买家重定向到该收银台地址完成补扣支付。
预览升级请求示例(仅展示 bizContent):
{
"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):
{
"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:用户选择“本周期结束后取消”
适合用户希望关闭自动续费,但继续使用当前已付款周期服务的场景。
建议做法:
- 先确认该订阅是否存在仍受 Update 门禁限制的计划变更;即使选择周期末取消,也不能绕过 Update 门禁。
- 调用 取消订阅,并传
cancelAtPeriodEnd=true。 - Cancel 成功后,在本地记录“已计划取消”,但不要立即停服。同步响应通常仍为
status=ACTIVE,并返回未来的cancelAt。 - 在当前计费周期结束前,继续按原状态提供服务。
- 等收到
notifyType=SUBSCRIPTION_CANCELLED(status=CANCELLED)的最终通知后,再停止续费与服务。
周期结束取消请求示例(仅展示 bizContent):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_CANCEL_202607150001",
"cancelAtPeriodEnd": true
}如果最终查询或通知返回如下结果,通常表示“当前周期已履约完成,订阅已真正结束”:
{
"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. 为补偿查询留兜底能力
即使已经接入通知,也建议保留主动查询逻辑:
- 订阅创建后长时间未收到通知时,查 查询订阅详情。
- 想核对每期支付明细时,查 查询订阅支付记录。
- 发生计划变更后需要核对结果时,查订阅详情并对照本地套餐版本。
- 发生 Update 退款或 Cancel 退款后,需要核对退款终态时,查订阅支付记录并结合退款通知处理。
查询订阅详情响应示例(仅展示 bizContent):
{
"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:获取订阅结果和支付结果。
