应用定期支付 | ONE store developer center

定期支付概要

定期支付是用户可以在规定的时间内使用服务，根据支付周期定期更新支付。

一般在使用音乐、电影或游戏时，都会使用定期支付服务。

开发者为了提供多种服务，可以在一个应用软件中配置多种定期支付商品，用户可以使用多种定期支付。

此外，为了确保新用户，可以以折扣价提供定期支付或提供免费体验的时间。

同样，也可以转换商品，让现有用户可以变更正在使用的定期支付商品。

处理定期支付

用户购买定期支付商品后,在使用商品期间可能进行多种状态变更。

应用软件要确认定期支付的状态，应对各状态的变更。

可以使用ONE store In-App支付library的PurchaseClient.queryPurchasesAsync() 或服务器API getSubscriptionDetail来确认定期支付状态。

定期支付状态变更后，将发回SubscriptionNotification。相关内容请参阅使用PNS(Push Notification Service)。

购买定期支付

用户购买定期支付后，PurchaseClient.queryPurchasesAsync()返回定期支付结果，并发送SUBSCRIPTION_PURCHASED的SubscriptionNotification。

接到该通知后,必须查询ONE store In-App支付API更新定期支付的状态。定期支付资源请参考以下示例。

{
+    "acknowledgementState": 0, // 购买新的定期付款时，需要acknowledge。
+    "autoRenewing": true,
     "paymentState": 1,
     "lastPurchaseId": "22071114040010115614",
     "linkedPurchaseToken": null,
     "priceAmount": "610",
     "priceAmountMicros": 610000000,
     "nextPriceAmount": "610",
     "nextPriceAmountMicros": 610000000,
     "nextPaymentTimeMillis": 1658106000000,
     "pauseStartTimeMillis": null,
     "pauseEndTimeMillis": null,
     "priceCurrencyCode": "KRW",
     "countryCode": "KR",
     "startTimeMillis": 1657515841000,
+    "expiryTimeMillis": 1658156399000,
     "autoResumeTimeMillis": null,
     "cancelledTimeMillis": null,
     "cancelReason": null,
     "promotionPrice": null,
     "priceChange": null
}

更新定期支付

定期支付更新后，会发送SUBSCRIPTION_RENEWED通知。

接到该通知后，必须查询ONE store In-App支付API，将定期支付状态更新到新的到期日。定期支付资源请参考以下示例。

{
+  "acknowledgementState": 1,
+  "autoRenewing": true,
   "paymentState": 1,
   "lastPurchaseId": "22071411443210116308",
   "linkedPurchaseToken": null,
   "priceAmount": "610",
   "priceAmountMicros": 610000000,   
   "nextPriceAmount": "610",
   "nextPriceAmountMicros": 610000000,
   "nextPaymentTimeMillis": 1658365200000,
   "pauseStartTimeMillis": nul,
   "pauseEndTimeMillis": null,
   "priceCurrencyCode": "KRW",
   "countryCode": "KR",
   "startTimeMillis": 1657766672000,
+  "expiryTimeMillis": 1658501999000,
   "autoResumeTimeMillis": null,
   "cancelledTimeMillis": null,
   "cancelReason": null,
   "promotionPrice": null,
   "priceChange": null
}

每月支付的商品，下一个月的同一天为支付日（3个月/6个月支付的商品同理）。

例如，如果1月15日开始定期支付，下一个支付日是2月15日。

但，如果没有相同的日期，当月的最后一天就是支付更新日。

例如，1月31日开始定期支付，下一个支付日是2月28日（或29日），再下一个支付日是3月28日（或29日）。

支付到期到期

定期支付到期后，PurchaseClient.queryPurchasesAsync()将不再返回，用户将无法使用定期支付。

SUBSCRIPTION_EXPIRED的SubscriptionNotification也将在定期支付到期时发送。

接到该通知后，必须查询ONE store In-App支付API，更新定期支付状态。定期支付资源请参考以下示例。

{    
     "acknowledgementState": 1,
+    "autoRenewing": false,
     "paymentState": 1,
     "lastPurchaseId": "22071213191410115875",
     "linkedPurchaseToken": null,
     "priceAmount": "610",
     "priceAmountMicros": 610000000,
     "nextPriceAmount": "610",
     "nextPriceAmountMicros": 610000000,
     "nextPaymentTimeMillis": 1658192400000,
     "pauseStartTimeMillis": null,
     "pauseEndTimeMillis": null,
     "priceCurrencyCode": "KRW",
     "countryCode": "KR",
     "startTimeMillis": 1657599554000,
+    "expiryTimeMillis": 1658242799000,
     "autoResumeTimeMillis": null,
     "cancelledTimeMillis": null,
     "cancelReason": null,    
     "promotionPrice": null,
     "priceChange": null
}

解除定期支付

用户可以在ONE store应用软件中直接解除定期支付,如果在支付手段出现问题时不解决，则会被自动解除定期支付。

也可以使用ONE store In-App支付API cancelRecurringPruchase解除定期支付。

即使用户直接解除定期支付,也要在目前定期支付期限结束之前可以使用服务。

如果已经解除定期支付但尚未到期时，PurchaseClient.queryPurchasesAsync()将被返回。定期支付解除后，将发送SUBSCRIPTION_CANCELED通知。

接到该通知后，必须查询ONE store In-App支付API，更新状态。查询时返回 autoRenewing=false和用户可以使用的服务期限expiryTimeMillis。

如果expiryTimeMillis期限是过去时间，服务会立即中断。如果期限是未来，一直使用服务到相应日期。定期支付资源请参考以下示例。

{
     "acknowledgementState": 1,
+    "autoRenewing": false,
     "paymentState": 1,
     "lastPurchaseId": "22071118111610115712",
     "linkedPurchaseToken": null,
     "priceAmount": "610",
     "priceAmountMicros": 610000000,
     "nextPriceAmount": "610",
     "nextPriceAmountMicros": 610000000,
     "nextPaymentTimeMillis": 1658106000000,
     "pauseStartTimeMillis": null,
     "pauseEndTimeMillis": null,
     "priceCurrencyCode": "KRW",
     "countryCode": "KR",
     "startTimeMillis": 1657515841000,
+    "expiryTimeMillis": 1658156399000,
     "autoResumeTimeMillis": null,
+    "cancelledTimeMillis": 1658156399000,
+    "cancelReason": 1,
     "promotionPrice": null,
     "priceChange": null
}

已解除用户的定期支付,应通过应用软件告知该定期支付的到期日期。（示例:定期支付已解除。定期支付将于2023年6月13日到期。 [确认])

取消定期支付

出于多种原因,用户可以取消定期支付。如果定期支付被取消,应立即禁止使用服务。

此时，PurchaseClient.queryPurchasesAsync()将不再返回，还会发送SUBSCRIPTION_REVOKED通知。

接到该通知后，必须查询ONE store In-App支付API，更新定期支付状态。

定期支付资源包括autoRenewing和定期支付使用期限expiryTimeMillis。定期支付资源请参考以下示例。

{    
     "acknowledgementState": 1,
+    "autoRenewing": false,
     "paymentState": null,
     "lastPurchaseId": "22071216245010115987",
     "linkedPurchaseToken": null,
     "priceAmount": "610",
     "priceAmountMicros": 610000000,
     "nextPriceAmount": "610",
     "nextPriceAmountMicros": 610000000,
     "nextPaymentTimeMillis": 1658192400000,
     "pauseStartTimeMillis": null,
     "pauseEndTimeMillis": null,
     "priceCurrencyCode": "KRW",
     "countryCode": "KR",
     "startTimeMillis": 1657610690000,
+    "expiryTimeMillis": 1657610749000,
     "autoResumeTimeMillis": null,
+    "cancelledTimeMillis": 1657610749000,
+    "cancelReason": 1,
     "promotionPrice": null,
     "priceChange": null
}

定期支付的宽限期

用户在使用定期支付时,支付手段出现了问题,如果问题得不到解决,定期支付不会立即解除。

如上所情况时，(1)延期支付 - 设定延期期限时(2) 按账户保留顺序变更定期支付状态。

是否提供延期支付期限,可在ONE store开发者中心进行设定。

如果设定了延期支付期限，用户必须在相应期间内可以使用定期支付内容。

如果在应用软件使用PurchaseClient.queryPurchasesAsync()来确认定期支付状态，PurchaseClient.queryPurchasesAsync()会在到期前持续返回定期支付状态，因此应用软件必须自动处理延期时间。

用户的定期支付状态被延期支付时,将发送SUBSCRIPTION_IN_GRACE_PERIOD通知。

接到该通知后,必须查询ONE store In-App结算API,更新状态。定期支付资源包括未来节点的expiryTimeMillis，以便适用autoRenewing=true和延期。

如果在延期时间内不解决支付问题,账户就会成为保留状态,用户将不能使用定期支付内容。

应用软件中应该显示信息,以便用户解决支付问题。

可以提供深度链接以帮助用户解决支付问题。

用户解决支付问题后,定期支付会立即更新。

{    
     "acknowledgementState": 0,
+    "autoRenewing": true,
     "paymentState": 0,
     "lastPurchaseId": "22071209533410115807",
     "linkedPurchaseToken": null,
     "priceAmount": "610",
     "priceAmountMicros": 610000000,
     "nextPriceAmount": "610",
     "nextPriceAmountMicros": 610000000,
     "nextPaymentTimeMillis": 1658192400000,
     "pauseStartTimeMillis": null,
     "pauseEndTimeMillis": null,
     "priceCurrencyCode": "KRW",
     "countryCode": "KR",
     "startTimeMillis": 1657587215000,
+    "expiryTimeMillis": 1658242799000,
     "autoResumeTimeMillis": null,
     "cancelledTimeMillis": null,
     "cancelReason": null,
     "promotionPrice": null,
     "priceChange": null
}

保留定期支付账户

用户在使用定期支付时,支付手段出现问题,如果问题得不到解决,延期期限结束后,账户将处于保留状态。

账户保留期限最长为30天,与延期期限不同,在账户保留状态下不能使用定期支付内容。

另外，账户保留期间， PurchaseClient.queryPurchasesAsync()不会返回定期支付。

如果用户的定期支付处于账户保留状态,将发送SUBSCRIPTION_ON_HOLD通知。

接到该通知后,必须调用ONE store In-App支付API,更新定期支付信息。在账户保留状态下，定期支付资源的expiryTimeMillis被设定为过去。在保留状态下,用户不能使用定期支付内容,超过指定的保留期限后,定期支付将被解除。

因此,要在应用软件中应该显示信息,以便用户能够解决问题。

可以提供深度链接以帮助用户解决问题。

用户解决问题后恢复定期支付的话,恢复那天变更为定期支付日。

账户保留期结束前,如果用户不解决问题,就会发送SUBSCRIPTION_CANCELED通知，必须查询ONE store In-App支付API,更新定期支付状态。

{
     "acknowledgementState": 0,
+    "autoRenewing": true,
     "paymentState": 0,
     "lastPurchaseId": "22071209361310115799",
     "linkedPurchaseToken": null,
     "priceAmount": "610",
     "priceAmountMicros": 610000000,
     "nextPriceAmount": "610",
     "nextPriceAmountMicros": 610000000,
     "nextPaymentTimeMillis": 1659315600000,
     "pauseStartTimeMillis": null,
     "pauseEndTimeMillis": null,
     "priceCurrencyCode": "KRW",
     "countryCode": "KR",
     "startTimeMillis": 1657586174000,
+    "expiryTimeMillis": 1658242799000,
     "autoResumeTimeMillis": null,
     "cancelledTimeMillis": null,
     "cancelReason": null,
     "promotionPrice": null,
     "priceChange": null
}

暂停定期支付

开发者可以在ONE store开发者中心设置暂停功能。

如果设置暂停功能，用户可以在一定时间内暂停定期支付，而不是取消订阅应用软件。

暂停是在目前定期支付中的商品到期后开始。用户在暂停期间不能使用定期支付内容。

暂停期间结束后，将重新开始定期支付。用户也可以在暂停期结束前直接解除暂停，重新开始定期支付。在这种情况下，解除暂停重新开始定期支付的日期成为定期支付日。

暂停时，PurchaseClient.queryPurchasesAsync()不被返回。恢复定期支付后，PurchaseClient.queryPurchasesAsync()被返回。如果用户选择暂停，将会发送SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED的SubscriptionNotification。

此时用户还留有定期支付的时间，因此必须能够继续使用定期支付的内容。

定期支付资源包括autoRenewing=true, paymentState=1和未来的expiryTimeMillis, autoResumeTimeMillis值。

{    
     "acknowledgementState": 1,
+    "autoRenewing": true,
+    "paymentState": 1,
     "lastPurchaseId": "22071114040010115614",
     "linkedPurchaseToken": null,
     "priceAmount": "610",
     "priceAmountMicros": 610000000,
     "nextPriceAmount": "610",
     "nextPriceAmountMicros": 610000000,
     "nextPaymentTimeMillis": 1660698000000,
+    "pauseStartTimeMillis": 1660748400000,
+    "pauseEndTimeMillis": 1663340399000,
     "priceCurrencyCode": "KRW",
     "countryCode": "KR",
     "startTimeMillis": 1657515841000,
+    "expiryTimeMillis": 1660748399000,
+    "autoResumeTimeMillis": 1660698000000,
     "cancelledTimeMillis": null,
     "cancelReason": null,
     "promotionPrice": null,
     "priceChange": null
}

暂停开始后，将发送SUBSCRIPTION_PAUSED的Subscription Notification。

如果开始暂停,定期支付使用期限就到期,因此不能再使用定期支付内容。

定期支付资源包括autoRenewing=true, paymentState=0和过去的expiryTimeMillis, autoResumeTimeMillis值。暂停期结束后,如果定期支付自动恢复或用户解除暂停并恢复定期支付,将发送SUBSCRIPTION_RENEWED 인 SubscriptionNotification。

此时需进行与"链接 - 定期支付更新"相同的处理。

恢复定期支付时，如果结算出现问题，就会发生定期支付账户保留状态，应进行与定期支付账户保留状态相同的处理。

{    
     "acknowledgementState": 1,
+    "autoRenewing": true,
+    "paymentState": 0,
     "lastPurchaseId": "22071114040010115614",
     "linkedPurchaseToken": null,
     "priceAmount": "610",
     "priceAmountMicros": 610000000,
     "nextPriceAmount": "610",
     "nextPriceAmountMicros": 610000000,
     "nextPaymentTimeMillis": 1663290000000,
+    "pauseStartTimeMillis": 1660748400000,
+    "pauseEndTimeMillis": 1663340399000,
     "priceCurrencyCode": "KRW",
     "countryCode": "KR",
     "startTimeMillis": 1657515841000,
+    "expiryTimeMillis": 1660748399000,
+    "autoResumeTimeMillis": 1663290000000,
     "cancelledTimeMillis": null,
     "cancelReason": null,
     "promotionPrice": null,
     "priceChange": null
}

商品变更（升级和降级）

如果用户将定期支付中的商品变更为其他定期支付商品，现有的定期支付将无效，新的定期支付将与新的购买token一起生成。

另外，定期支付资源中还包括表示现有定期支付的linkedPurchaseToken。

使用"inkedPurchaseToken可以查询以前的定期支付，将新的定期支付与同一账户进行连接。

已经创建了新的定期支付，需对该支付进行"链接 - 购买确认"。定期支付资源请参考以下示例。

{
    "acknowledgementState": 1, 
    "autoRenewing": true,
    "paymentState": 1,
    "lastPurchaseId": "22071214572510115940",
+   "linkedPurchaseToken": "220712131914S0115875",
    "priceAmount": "600",
    "priceAmountMicros": 600000000,
    "nextPriceAmount": "600",
    "nextPriceAmountMicros": 600000000,
    "nextPaymentTimeMillis": 1660266000000,
    "pauseStartTimeMillis": null,
    "pauseEndTimeMillis": null,
    "priceCurrencyCode": "KRW",
    "countryCode": "KR",
    "startTimeMillis": 1657605449000,
    "expiryTimeMillis": 1660316399000,
    "autoResumeTimeMillis": null,
    "cancelledTimeMillis": null,
    "cancelReason": null,
    "promotionPrice": null,
    "priceChange": null
}

打开定期支付的管理界面

ONE store为用户提供定期支付管理菜单，以便管理定期支付商品。

如果将PurchaseData作为参数放入SubscriptionsParams中，则确认购买数据，并运行相应定期支付商品的管理界面。 SubscriptionParams输入null时，将运行用户的定期支付列表界面。

以下是显示定期支付管理界面的示例。

fun launchManageSubscription(@Nullable purchaseData: PurchaseData) {
    .val subscriptionParams = when (purchaseData != null) {
true -> SubscriptionParams.newBuilder()
.setPurchaseData(purchaseData)
.build()
else -> null
}
purchaseClient.launchManageSubscription(mActivity, subscriptionParams)
}

public void launchManageSubscription(@Nullable PurchaseData purchaseData) {
SubscriptionParams subscriptionParams = null;
if (purchaseData != null) {
       subscriptionParams = SubscriptionParams.newBuilder()
.setPurchaseData(purchaseData)
.build();
}
purchaseClient.launchManageSubscription(mActivity, subscriptionParams);
}

变更定期支付商品

用户可能想在定期支付中改变计划，购买更好或更便宜的定期支付商品。

用户可以通过支付其他定期支付商品来变更定期支付商品，开发者可以设定比例分配模式来处理定期支付商品的变更。

可设定的比例分配模式(PurchaseFlowParams.ProrationMode)如下。

比例分配示例

用户现在每月定期支付商品A。该定期支付需要支付2000韩元，每月1日更新。

4月15日，用户决定将商品变更为年定期支付商品B，费用为每年36,000韩元。 IMMEDIATE_WITH_TIME_PRORATION

定期支付商品A立即终止。用户支付了一个月（4月1日~30日）的费用，在定期支付期间中间变更了商品，因此每月定期支付费用的一半（1,000韩元）将适用于新的定期支付。但是新的定期支付费用为每年36,000韩元,因此,1000韩元的余额相当于10天(4月16日~25日)。因此,4月26日需要支付新的定期支付费用36,000韩元,从第二年开始每年4月26日需支付36,000韩元。 IMMEDIATE_AND_CHARGE_PRORATED_PRICE

每小时定期支付商品B的价格(36,000韩元/年= 3000韩元/月)高于定期支付商品A的价格(2000元/月)，因此可使用此模式。而定期支付商品A立即终止。用户结算了一个月的全部费用，但只使用了期间的一半，所以每月定期支付费用的一半(1000韩元)适用于新的定期支付。新的定期支付费用是一年36,000韩元，剩下的15天的费用是1500元。因此，作为新的定期支付费用，需要支付500韩元的差额。5月1日，新定期支付商品B的费用为36,000韩元，从第二年开始每年5月1日的费用为36,000韩元。 IMMEDIATE_WITHOUT_PRORATION

定期支付商品A立即变更为定期支付商品B，不需要追加费用。5月1日,新定期支付商品B的费用是36,000韩元，从第二年开始每年5月1日支付费用是36,000韩元。 DEFERRED

定期支付商品A将持续到4月30日到期为止。5月1日适用定期支付商品B，作为新的定期支付费用，用户需支付36,000韩元。定期支付可以使用与"请求购买"相同的API为用户提供商品变更功能。但是，为了变更定期支付的商品,必须具备现有的定期支付购买token和比例分配模式值。

如下列例子，需要提供关于定期支付和变更后适用的定期支付及比例分配模式的相关信息。

val subscriptionUpdateParams = SubscriptionUpdateParams.newBuilder()
.setProrationMode(desiredProrationMode)
.setOldPurchaseToken(oldPurchaseToken)
.build()

val purchaseFlowParams = PurchaseFlowParams.newBuilder()
.setProductId(newProductId)
.setProductType(productType)
.setProductName(productName) // optional
.setDeveloperPayload(devPayload) // optional
    .setSubscriptionUpdateParams(subscriptionUdpateParams)
.build()

purchaseClient.launchPurchaseFlow(activity, purchaseFlowParams)

SubscriptionUpdateParams subscriptionUpdateParams = SubscriptionUpdateParams.newBuilder()
.setProrationMode(desiredProrationMode)
.setOldPurchaseToken(oldPurchaseToken)
.build();

PurchaseFlowParams purchaseFlowParams = PurchaseFlowParams.newBuilder()
.setProductId(newProductId)
.setProductType(productType)
.setProductName(productName) // optional
     .setDeveloperPayload(devPayload) // optional
    .setSubscriptionUpdateParams(subscriptionUdpateParams)
.build();

purchaseClient.launchPurchaseFlow(activity, purchaseFlowParams);

对于立即进行变更的比例分配模式,由于执行"请求购买"逻辑,所以响应由PurchasesUpdatedListener接收。此外，还可以在"查询购买订单"中得到响应。

必须使用PurchaseClient.acknowledgeAsync()或acknowledgePurchase进行"确认购买"处理。

ONE store的In-App支付API从定期支付资源中返回linkedPurchaseToken。linkedPurchaseToken应该无效化，以避免以前的tokne被用于获得内容使用权限。对于变更延迟的比例分配模式，接收定期支付的购买及变更与否的同时接收PurchasesUpdatedListener调用。

直到变更适用，PurchaseClient.queryPurchasesAsync()继续返回现有定期支付商品的购买信息。

变更适用后，PurchaseClient.queryPurchasesAsync()会返回新定期支付商品的购买信息，发送SUBSCRIPTION_RENEWED的Subscription Notification。

如果发生变更延迟，最好接收此通知并使用acknowledgePurchase进行购买确认处理。.

变更为有促销活动的商品

ONE store在使用促销活动的定期支付商品时,不能变更为其他商品。

但是,成为变更对象的商品即使适用促销活动,也可以进行变更。

如果顾客想继续使用变更对象的商品促销活动，必须应用IMMEDIATE_WITH_TIME_PRORATION模式。

除此之外的其他比例分配模式的情况是,即使变更对象商品适用促销活动,也不能使用促销活动。

推迟定期支付期限

使用ONE store In-App支付API的deferSubscription，可以推迟定期支付用户的下一个支付日。

推迟期间，用户可以对内容进行access。

定期支付期限的延期可以在以下情况下使用。

通过特别活动,使现有用户在一周内额外使用定期支付。
由于系统故障等原因,可以给顾客追加使用期限。

每个API调用可以将支付期限从最少一天推迟到最多一年。如果要再次延期支付，只需在期限内再次调用API。延期支付时,可以在电子邮件或应用软件内发送通知,告知支付日期变更。

更改定期支付价格

在ONE store开发者中心可以变更定期支付商品的价格。

定期支付商品的基本价格变更后，新的购买会立即反映变更的价格。

但是，对于现在使用定期支付的顾客，7天后会收到变更价格的通知，之后30天会被提供价格变更同意期间。

如果在期限内不同意变更价格，该定期支付将在下一个定期支付日取消。

(如果价格下降或维持不变，无需另行通知或同意，7日后在下一个更新日以变更价格支付。)

同意变更价格时

用户同意提高订阅费用或降低价格时，在同意期限后以变更的价格支付。

另外，将发送SUBSCRIPTION_PRICE_CHANGE_CONFIRMED的Subscription Notification。

不同意变更价格时

如果用户不同意提高订阅费用，定期支付将自动取消，并发送SUBSCRIPTION_REVOKED的Subscription Notification。

因失误变更价格时

如果因失误变更了定期支付价格,最好重新返回价格。

如果在7天内恢复价格,则不会对现有定期支付用户造成影响。

但是,在这种情况下,新购买的顾客也会以变更的价格支付,因此价格变更要慎重。

发生两次价格变更时

如果第一次价格变更后的第二次价格变更是在7天以内,那么第一次价格变更将无效,只适用第二次价格变更。

但,如果第二次价格变更是在7天以后,用户必须同意两次价格变更。

对价格变更的同意程序会给用户带来不便,维持相应定期支付商品的顾客很有可能会减少。

再次强调，价格变更要慎重。