Subscription payment system

Auto-renewable subscriptions¶

Hive SDK v4.11.6 supports new feature called auto-renewable subscriptions, which repeats payment on a regular basis. The types of subscription are monthly subscription, yearly subscription, and free trials in general. If you like to know more about the subscription format provided by Google and Apple, refer to the following table. Auto-renewable subscriptions are available if user selects the period of regular payment by OS type.

Make sure to let your game users access the auto-renewable subscriptions at any time regardless of device type if the user is regularly charged a specific subscription. Subscription restoration is essential feature in accordance with user needs.

Price change Auto-renewal subscriptions are free to upgrade or downgrade the subscription level. Subscriptions are not a single-use, and provide receipt when users try to reinstate.

On Google, subscriptions are free to upgrade or downgrade the subscription level and change to new one regardless of previous subscription. If the user changes the price, the value of previous subscription is calculated on a daily basis and provided after the expiry of the new subscription.

On Apple platforms, subscription group is defined on iTunes console, so change to one of other subscription types in a same group is available. If the user upgrades his/her subscription, the value of previous subscription is calculated on a daily basis and provided after the expiry of the new subscription. In case of downgrade, it renews to the new subscription after the existing subscription is expired.

Purchase, restoration and grace period¶

Purchase¶

• Free trials If a subscription has free-trial period, it is not calcualted as sales. After free-trial expires, the subscription is charged automatically.
• Discount for new subscribers It is a promotion for new subscribers. This promotion is available in a specific period of time with discounted prices.

Cancellation¶

Subscribers can cancel the subscription prior to renewal period. How to cancel is described in Manage Subscriptions menu from each market. After the subscription canceled, auto-renewal is expired.

Refund¶

If a subscriber request to refund the rest value of the subscription after cancellation, the amount of refund is calculated based on the rest of time period and the value of subscription (Google console).

Restoration¶

Subscribers can reinstate the subscription if the subscription is unavailable after payment. Value calculation for restoration is based on the ownership policy if a subscriber has the ownership of the subscription.

Grace period¶

When subscription renewal is failed to charge, use grace period. Make sure to value the state in grace period as same as that of subscription.

Account hold (Google)¶

Account hold is a state that fails to renew a subscription due to issues occurred at the moment of payment, and ends with unsolved issues. In this case, make sure to process the subscription unavailable for maximum 30 days.

Pause (Google)¶

Pausing subscription is available for maximum three months. When the period ends, the subscription is automatically resumed.

Displaying Google notification popup¶

If Google subscription state is in grace period or on account hold, display a notification popup. The popup should contain the current subscription state, how to solve issues and a button that links to market settings. This button is not essential in the grace period, however, it is recommended for user convenience. In case the user changes the payment information in the grace period or on hold state, the subscription is automatically paid at the moment the user is set in case of the grace period state. On the account hold, the user should restart the subscription. When the subscription state of users is renewed after the restart, provide a subscription purchase page and a restoration button for users to give benefits of their subscription.

Notification popup samples are as follows. Use these phrases or customize them for each game. * Notification Phrases in Grace Period

• Notification Phrases when it is in pending state

Purchase process of subscription¶

Diagram¶

Flowchart¶

Google subscription V2 support¶

Google subscription API V2 allows you to create and manage multiple benefits using a new subscription method. The examples of the benefits include a benefit on your first subscription, and a discount by subscribing an additional product when you already had a subscription. For more information on Google subscriptions, see here.

If you use Google subscription V2, you can grant differentiated benefits to the payment price according to the subscription status, such as the subscription period and the number of the past subscriptions. To use Google subscription V2, please follow the steps below.

Register product in the Google Play Console¶

Register your products to be sold using Google subscription V2 on the Google Play Console. For more details, please refer to Play Console Guide.

Check the registered product information with getSubscriptionProductInfo¶

You can check your product information registered in the Google Play Console at the response value of IAPV4.getSubscriptionProductInfo method, the originalMarketJson of the IAPV4Product object. * productId: product * basePlanId: subscription plan * offerIdToken: benefit

The below presents an example product called "sub003" whose information can be found in originalMarketJson, after registering a weekly and a monthly payment each and defining two benefits for the monthly payment.

{
    "productId": "sub003",
    "type": "subs",
    "title": "sub003-name (HIVE SDK)",
    "name": "sub003-name",
    "localizedIn": [
        "ko-KR"
    ],
    "skuDetailsToken": "AEuhp4KfxD0MTrwzJV_jl0exSz9NuCZzipMe8mo45lR7pi3y_bWsvXdeKNM04CMxxNY=",
    "subscriptionOfferDetails": [
        {
            "offerIdToken": "AUj\/Yhj7Zx5lt7B0G4qWDtmPFDioPkobZB7zw0xi1A8+B4iD0AbZbwQJKitQLCjR9CMLssbH+g43p4wf3tLREE8H41NgdDpOaCsla0xoTQKPkCsH6+U4XszzPUtOGNwuskbzNjEDfTJoF50j1fSd+IXCkQ==",
            "basePlanId": "baseprice-p1m",
            "offerId": "offer-freetrial",
            "pricingPhases": [
                {
                    "priceAmountMicros": 0,
                    "priceCurrencyCode": "KRW",
                    "formattedPrice": "free",
                    "billingPeriod": "P1M",
                    "recurrenceMode": 2,
                    "billingCycleCount": 1
                },
                {
                    "priceAmountMicros": 1650000000,
                    "priceCurrencyCode": "KRW",
                    "formattedPrice": "₩1,650",
                    "billingPeriod": "P1M",
                    "recurrenceMode": 2,
                    "billingCycleCount": 2
                },
                {
                    "priceAmountMicros": 3300000000,
                    "priceCurrencyCode": "KRW",
                    "formattedPrice": "₩3,300",
                    "billingPeriod": "P1M",
                    "recurrenceMode": 1
                }
            ],
            "offerTags": [
                "offer-free",
                "offer-freetrial"
            ]
        },
        {
            "offerIdToken": "AUj\/YhjUXnT6K8XbdZd5lUtCSef0HA+qikjGfNPEAXvLeLKWTZ0RqwcFIvR5GhECXTRD1SdUrn0LcaB6oquBo5QeUTEZJGTstWGzfmrwL3oSsvBs1EERERSdJ6NDq54=",
            "basePlanId": "baseprice-p1m",
            "pricingPhases": [
                {
                    "priceAmountMicros": 3300000000,
                    "priceCurrencyCode": "KRW",
                    "formattedPrice": "₩3,300",
                    "billingPeriod": "P1M",
                    "recurrenceMode": 1
                }
            ],
            "offerTags": []
        },
        {
            "offerIdToken": "AUj\/YhhlJDIsjfnvcc5TfxlBjSA+o3QcNsCAjU+DfXBJn2JF\/zLgew468AvchceNBynmB3CvnPLhqlr8be8dJlIvAEkKgdas1DGoiu3p52jSvwsxh8jQLN7QReXUdrY=",
            "basePlanId": "baseprice-p1w",
            "pricingPhases": [
                {
                    "priceAmountMicros": 500000000,
                    "priceCurrencyCode": "KRW",
                    "formattedPrice": "₩500",
                    "billingPeriod": "P1W",
                    "recurrenceMode": 1
                }
            ],
            "offerTags": []
        }
    ]
}

There are a total of 3 benefit key values shown in the offerIdToken example above, 2 benefit types for the monthly payment and 1 base benefit for the weekly payment. The first or the second benefit will actually be applied to the users when making monthly payment.

Request subscription¶

Request a subscription as shown below using IAPV4Product object originalMarketJson obtained above. You can request a subscription with applying the corresponding benefits to the user.

using hive;    
    IAPV4PurchaseParam.Builder builder = new IAPV4.IAPV4PurchaseParam.Builder();    
    IAPV4PurchaseParam param = builder.setMarketPid("YOUR_PRODUCT_MARKET_PID")    
    .setOldMarketPid("YOUR_PRODUCT_OLD_MARKET_PID")    
    .setIapPayload("YOUR_PAYLOAD")    
    .setOfferToken("YOUR_OFFER_ID_TOKEN")    
    .build();    

    IAPV4.purchaseSubscription (param, (ResultAPI result, IAPV4Receipt receipt) => {    
        if (result.isSuccess()) {    
        // TODO: Request verification of receipt with received receipt    
        }    
});

#include "HiveIAPV4.h"

FHiveIAPV4PurchaseParam Param;
Param.MarketPid = TEXT("YOUR_PRODUCT_MARKET_PID");
Param.OldMarketPid = TEXT("YOUR_PRODUCT_OLD_MARKET_PID");
Param.IapPayload = TEXT("YOUR_PAYLOAD");
Param.OfferToken = TEXT("YOUR_OFFER_ID_TOKEN");

FHiveIAPV4::PurchaseSubscription(Param, FHiveIAPV4OnPurchaseDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveIAPV4Receipt& Receipt) {
        if (Result.IsSuccess()) {
                // TODO: Request verification of receipt with received receipt
        }
}));

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    auto* param = new IAPV4PurchaseParam();    
    param->marketPid = "YOUR_PRODUCT_MARKET_PID";    
    param->oldMarketPid = "YOUR_PRODUCT_OLD_MARKET_PID";    
    param->iapPayload = "YOUR_PAYLOAD";    
    param->offerToken = "YOUT_OFFER_ID_TOKEN";    

    IAPV4::purchaseSubscription(*param, [=](ResultAPI const & result, IAPV4Receipt const & receipt) {    
         if (result.isSuccess()) {    
             // TODO: Request verification of receipt with received receipt    
         }    
});

import com.hive.IAPV4    
    import com.hive.ResultAPI    
    val param = IAPV4.IAPV4PurchaseParam.Builder()    
    .setMarketPid("YOUR_PRODUCT_MARKET_PID")    
    .setOldMarketPid("YOUR_PRODUCT_OLD_MARKET_PID")    
    .setIapPayload("YOUR_PAYLOAD")    
    .setOfferToken("YOUR_OFFER_ID_TOKEN")    
    .build()    
    IAPV4.purchaseSubscription(param, object : IAPV4.IAPV4PurchaseListener {    
         override fun onIAPV4Purchase(result: ResultAPI, receipt: IAPV4.IAPV4Receipt?) {    
             if (result.isSuccess) {    
                 // TODO: Request verification of receipt with received receipt    
             }    
         }    
})

import com.hive.IAPV4;    
    import com.hive.ResultAPI;    
    IAPV4.IAPV4PurchaseParam param = new IAPV4.IAPV4PurchaseParam.Builder()    
             .setMarketPid("YOUR_PRODUCT_MARKET_PID")    
             .setOldMarketPid("YOUR_PRODUCT_OLD_MARKET_PID")    
             .setIapPayload("YOUR_PAYLOAD")    
             .setOfferToken("YOUR_OFFER_ID_TOKEN")    
             .build();    
    IAPV4.INSTANCE.purchaseSubscription(param, (result, iapV4Receipt) -> {    
         if (result.isSuccess()) {    
             // TODO: Request verification of receipt with received receipt    
         }    
});

import HIVEService    
    let param = IAPV4PurchaseParam.Builder()    
    .setMarketPid("YOUR_PRODUCT_MARKET_PID")    
    .setOldMarketPid("YOUR_PRODUCT_OLD_MARKET_PID")    
    .setIapPayload("YOUR_PAYLOAD")    
    .setOfferToken("YOUR_OFFER_ID_TOKEN")    
    .build()    

    IAPV4Interface.purchaseSubscription(param) { result, receipt in    
        if result.isSuccess() {    
        // TODO: Request verification of receipt with received receipt    
        }    
}

#import <HIVEService/HIVEService-Swift.h>    
    HIVEIAPV4PurchaseParamBuilder *builder = [[HIVEIAPV4PurchaseParamBuilder alloc] init];    
    HIVEIAPV4PurchaseParam *param = [[[[[builder setMarketPid: @"YOUR_PRODUCT_MARKET_PID"]    
    setIapPayload: @"YOUR_PRODUCT_OLD_MARKET_PID"]    
    setOldMarketPid: @"YOUR_PAYLOAD"]    
    setOfferToken: @"YOUR_OFFER_ID_TOKEN"]    
    build];    

    [HIVEIAPV4 purchaseSubscription: param handler: ^(HIVEResultAPI *result, HIVEIAPV4Receipt *receipt) {    
        if ([result isSuccess]) {    
        // TODO: Request verification of receipt with received receipt    
        }    
}];

Subscription API¶

Get subscription product list¶

When a user enters the subscription product shop in the game, the IAPV4.getSubscriptionProductInfo() method which queries the list of subscription products must be called. When this API is called, the IAPV4Product object which contains the product list and product information will be returned as the result. The IAPV4Product object is similar to the one returned in Searching Product List.

IAPV4Product object¶

displayPrice¶

• Send the displayPrice with the combination of currency sign and price in order (e.g. $0.99). As Android or iOS has its own display type, the order of currency sign and price may show up differently in several countries depending on the OS.
• Make sure to output the currency sign of each country as the same with its table. Refer to the Hive Identifier Policy to confirm the table of currency sign.
• In case of additional countries to add or change VAT, server calculates VAT of all currency and adds to displayPrice, price, displayOriginalPrice andoriginalPrice. Therefore, you have no more work relevant to VAT.

Followings are sample codes to implement getSubscriptionProductInfo() method.

```None linenums="1"
// Request to search subscription lists
IAPV4::getSubscriptionProductInfo([=](ResultAPI const & result, std::vector const & productInfoList, unsigned int balance) {
        if (result.isSuccess()) {
                for( auto productInfo : productInfoList) {
                        // Implementation of the desired features by the game studio, such as shop UI.
                }
        }
        else {
                // Error Handling
        }
});
```

#include "HiveIAPV4.h"

FHiveIAPV4::GetSubscriptionProductInfo(FHiveIAPV4OnProductInfoDelegate::CreateLambda([this](const FHiveResultAPI& Result, const TArray<FHiveIAPV4Product>& ProductInfoList, uint32 Balance) {

        if (Result.IsSuccess()) {
                for (const auto& ProductInfo : ProductInfoList) {
                        // Implementation of the desired features by the game studio, such as shop UI.
                }
        } else {
                // Error Handling
        }
}));

// Request to search subscription lists    
    IAPV4.getSubscriptionProductInfo(new IAPV4.IAPV4ProductInfoListener() {    
        @Override    
        public void onIAPV4ProductInfo(ResultAPI result, final List iapV4ProductList, final int balance) {    
            if (result.isSuccess()) {    
                for (IAPV4Product productInfo : iapV4ProductList) {    
                // Implementation of the desired features by the game studio, such as shop UI.    
                }    
            } else {    
                // Error Handling    
            }    
        }    
});

// Request to search subscription lists
    IAPV4.getSubscriptionProductInfo(new IAPV4.IAPV4ProductInfoListener() {
            @Override
            public void onIAPV4ProductInfo(ResultAPI result, final List iapV4ProductList, final int balance) {
                    if (result.isSuccess()) {
                            for (IAPV4Product productInfo : iapV4ProductList) {
                            // Implementation of the desired features by the game studio, such as shop UI.
                            }
                    } else {
                            // Error Handling
                    }
            }
    });

    // Request to search subscription lists
    [HIVEIAPV4 getSubscriptionProductInfo:^(HIVEResultAPI *result, NSArray *productInfoList, NSUInteger balance) {
            if( [result isSuccess]) {
                    for( HIVEIAPV4Product* productInfo in productInfoList) {
                            // Implementation of the desired features by the game studio, such as shop UI.
                    }
            } else {
                    // Error Handling
            }

    }];

Purchase subscription product¶

Call the IAPV4 class purchaseSubscriptionUpdate() method to request subscription purchase using MarketPid registered in Apple App Store and Google Play Store as a parameter.

The following is an example implementation of purchaseSubscriptionUpdate().

```unity linenums="1"
std::string marketPid = "{YOUR_PRODUCT_MARKET_PID}";
std::string oldMarketPid = "{YOUR_PRODUCT_OLD_MARKET_PID}";
std::string iapPayload = "{YOUR_PRODUCT_IAP_PAYLOAD}";

// Request to purchase subscription products
IAPV4::purchaseSubscriptionUpdate(marketPid, oldMarketPid, iapPayload, [=](ResultAPI const & result, IAPV4Receipt const & receipt) {
        if (result.isSuccess()) {
                                // Request to verify the receipt with the received receipt
        }
        else {
                // Error Handling
        }
});
```

```c++ linenums="1"
std::string marketPid = "{YOUR_PRODUCT_MARKET_PID}";
std::string oldMarketPid = "{YOUR_PRODUCT_OLD_MARKET_PID}";
std::string iapPayload = "{YOUR_PRODUCT_IAP_PAYLOAD}";

// Request to purchase subscription products
IAPV4::purchaseSubscriptionUpdate(marketPid, oldMarketPid, iapPayload, [=](ResultAPI const & result, IAPV4Receipt const & receipt) {
        if (result.isSuccess()) {
                                // Request to verify the receipt with the received receipt
        }
        else {
                // Error Handling
        }
});
```

val marketPid = "{YOUR_PRODUCT_MARKET_PID}"    
    val oldMarketPid = "{YOUR_PRODUCT_OLD_MARKET_PID}"    
    val iapPayload = "{YOUR_PRODUCT_IAP_PAYLOAD}"    


    // Request to purchase subscription products    
    IAPV4.purchaseSubscriptionUpdate(pid, oldMarketPid, iapPayload, object : IAPV4.IAPV4PurchaseListener {    
        override fun onIAPV4Purchase(result: ResultAPI, iapV4Receipt: IAPV4.IAPV4Receipt?) {    
            if (result.isSuccess()) {    
                    // Request to verify the receipt with the received receipt    
            } else {    
                   // Error Handling    
            }    
        }    
})

String marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
    String oldMarketPid = "{YOUR_PRODUCT_OLD_MARKET_PID}";    
    String iapPayload = "{YOUR_PRODUCT_IAP_PAYLOAD}";    


    // Request to purchase subscription products    
    IAPV4.purchaseSubscriptionUpdate(pid, oldMarketPid, iapPayload, new IAPV4.IAPV4PurchaseListener() {    
        @Override    
        public void onIAPV4Purchase(ResultAPI result, IAPV4.IAPV4Receipt iapV4Receipt) {    
            if (result.isSuccess()) {    
                    // Request to verify the receipt with the received receipt    
            } else {    
                   // Error Handling    
            }    
        }    
});

let marketPid = "{YOUR_PRODUCT_MARKET_PID}"    
    let oldMarketPid = "{YOUR_PRODUCT_OLD_MARKET_PID}"    
    let iapPayload = "{YOUR_PRODUCT_IAP_PAYLOAD}"    

    // Request to purchase subscription products    
    HIVEIAPV4.purchaseSubscriptionUpdate(marketPid, oldMarketPid: oldMarketPid, iapPayload: iapPayload) { result, receipt in    
        if result.isSuccess() {    
            // Request to verify the receipt with the received receipt    
        } else {    
            // Error Handling    
        }    
}

NSString* marketPid = @"{YOUR_PRODUCT_MARKET_PID}";    
    NSString* oldMarketPid = @"{YOUR_PRODUCT_OLD_MARKET_PID}";    
    NSString* iapPayload = @"{YOUR_PRODUCT_IAP_PAYLOAD}";    

    // Request to purchase subscription products    
    [HIVEIAPV4 purchaseSubscriptionUpdate:marketPid oldMarketPid:oldMarketPid iapPayload:iapPayload handler:^(HIVEResultAPI *result, HIVEIAPV4Receipt *receipt) {    
        if ([result isSuccess]) {    
                    // Request to verify the receipt with the received receipt    
        } else {    
                   // Error Handling    
        }    
}];

Restoring subscription state¶

If the current subscription is not available on the subscriber's device, implement restoreSubscription() method in the IAPV4 class to restore the subscription and request the receipt of the charged subscription.

Followings are sample codes to implement restoreSubscription() method.

using hive;    
    IAPV4.restoreSubscription((ResultAPI result, List<IAPV4Receipt> receiptList) => {    
    if (result.isSuccess()) {    
    // TODO: Request receipt verification using the received receiptList    
         }    
});

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    IAPV4::restoreSubscription([=](ResultAPI const & result, vector<reference_wrapper<IAPV4Receipt>> receiptList) {    
         if (result.isSuccess()) {    
    // TODO: Request receipt verification using the received receiptList    
         }    
});

import com.hive.IAPV4    
    import com.hive.ResultAPI    
    IAPV4.restoreSubscription(object : IAPV4.IAPV4RestoreListener {    
         override fun onIAPV4Restore(result: ResultAPI, iapv4ReceiptList: ArrayList<IAPV4.IAPV4Receipt>?) {    
             if (result.isSuccess) {    
                 // TODO: Request receipt verification using the received iapv4ReceiptList    
             }    
         }    
})

import com.hive.IAPV4;    
    import com.hive.ResultAPI;    
    IAPV4.INSTANCE.restoreSubscription((result, iapv4ReceiptList) -> {    
         if (result.isSuccess()) {    
             // TODO: Request receipt verification using the received iapv4ReceiptList    
         }    
});

import HIVEService    
    IAPV4Interface.restoreSubscription() { result, receiptList in    
    if result.isSuccess() {    
    // TODO: Request receipt verification using the received receiptList    
    }    
}

#import <HIVEService/HIVEService-Swift.h>    
    [HIVEIAPV4 restoreSubscription: ^(HIVEResultAPI *result, NSArray<HIVEIAPV4Receipt *> *receiptList) {    
         if ([result isSuccess]) {    
    // TODO: Request receipt verification using the received receiptList    
         }    
}];