IAP v4 notifying real-time subscription
With real-time subscription notifications, the game server receives user subscription status information from the Hive IAP server in real time. Users can implement subscription suspension, hold, and pause functions with this information.
Warning
To use the real-time subscription notifications feature, you must set a notification URL in the Market Consol.
The real-time subscription notification API works by making calls from the Hive IAP server to the game server, and includes subscription status change information in the Request Body and transmits it in real-time. Since the game server receives subscription status change information, it must provide the API endpoint (URL) to Hive.
The API URL can be registerted in the Hive Console > App Center > Game List > Game details > Game server > Market Server Notification URL. If the game server is divided by region and each region should receive notifications, provide the URL one by one. Then, IAP sends notifications to all game servers.
IAP sends the real-time subscription state from Hive Server to game server. Therefore, make sure that game server opens the inbound firewall of the following server IP to get notifications.
- 43.202.181.138
- 3.38.239.17
-
Request Specification ( IAP > Game server)
Field Name Description Type Required notification_type notification type; Apple - Google: The subscription in grace period/on hold/paused are based on the value of hiveiap_receipt_subscription_state. Please use this field as a reference data.String Y sub_type The subtype of notification. It is only for the Apple notification subtype info. String N hiveiap_market_id Paid market code 1. Apple App Store 2. Google Play Store Integer Y hiveiap_receipt_verify_result Verification result of the receipt sent from market verification server - Apple Receipt Verification Result Guide (Storekit 1, before iOS 15) - Apple Receipt Verification Result Guide (Storekit 2, iOS 15 or later) - Google Subscription V1 Verification Result Guide - Google Subscription V2 Verification Result Guide Object Y hiveiap_receipt_start_date_ms the start time of the subscription (Unix TimeStamp Milliseconds) String Y hiveiap_receipt_expire_date_ms the end time of the subscription (Unix TimeStamp Milliseconds) If this value was changed, you need to apply this in your game for all notification types. For example, you need to change the subscription expiry date of a user’s game item in your game. String Y hiveiap_receipt_autoresume_date_ms - the subscription resumed time if a subscription was paused (Unix TimeStamp Milliseconds) - “” is received if a subscription was not paused String N hiveiap_receipt_subscription_state the subscription status 1. Active 2. In grace period 3. On hold 4. Paused 5. Expired Currently only Google subscription data is available to be sent. Account hold and restoration features are essential from November 1st, 2020 by following the revised Google policy. This API checks the subscription state. - Grace period: It extends the expiry until the payment state of user is back to normal (Applied only in the grace period set on Google Play Console). - Account holding: Permission for using a content is not granted as payment has issues as well as expiration time ends, but it extends the subscription expiry time when restoring the paid subscription after payment state is back to normal (Keeps the holding state for maximum 30 days). Integer N hiveiap_apple_info This object has the key value to identify a subscription receipt in the Apple subscription receipt verification results. This is only used for an App Store subscription receipt. Deliver only when the response code is 0 (Verification success). Object N ㄴ original_transaction_id This is the key value to identify an Apple subscription receipt. For an App Store account, this value remains the same for the same product purchased, or for a product within the same group that is upgraded, downgraded, repurchased or whose purchase is canceled (16 characters allowed but it can vary since there is no specific guide about the length of this string). String N hiveiap_google_info the key value to identify a receipt in the Google subscription receipt verification results Subscription receipt on Play Store only. It sends the value only when response code is 0 (verification success). Object N ㄴ purchase_token Purchase token in the receipt. The token value requires 200 characters and more, and length change is available due to no limitation on Google guide. String N ㄴ purchase_token_hash It is generated by hashing the value of purchase_tokenfield (sha1). Due to long length ofpurchase_tokenvalue, it processes hashing to search from and save on database in esase (40 characters).String N ㄴ linked_purchase_token If subscription receipt is newly issued after upgrade, downgrade, cancellation, or re-activation, the value of this field can identify the purchase tokens in old reciepts. It recommends to expire by force if the are values. The token value requires 200 characters and more, and length change is available due to no limitation on Google guide. (However, no new issuance in case of reactivation on Play Store) String N ㄴ linked_purchase_token_hash It is generated by hashing the value of linked_purchase_tokenfield (sha1). Due to long length oflinked_purchase_tokenvalue, it processes hashing to search from and save on database in esase (40 characters).String N hiveiap_iap_payload This is the purchase meta information defined by game company. If no meta information defined, it returns null.String Y hiveiap_receipt_cancel_date_ms This is the time (unix timestamp, ms) when a subcription was cancelled. The default value is 0. Integer Y hiveiap_receipt_refund_date_ms This is the time (unix timestamp, ms) when a purchase refund was made. The default value is 0. Integer Y -
Call ( IAP > Game server)
curl -L -v
-d '{"notification_type":"SUBSCRIBED","sub_type":"RESUBSCRIBE","hiveiap_market_id":1,"hiveiap_market_pid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.arshive001","hiveiap_receipt_verify_result":{"status":0,"receipt":{"transactionId":"2000000326618738","originalTransactionId":"2000000287618347","webOrderLineItemId":"2000000026848658","bundleId":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","productId":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.arshive001","subscriptionGroupIdentifier":"20519034","purchaseDate":1683534980000,"originalPurchaseDate":1677492217000,"expiresDate":1683535160000,"quantity":1,"type":"Auto-Renewable Subscription","appAccountToken":"5e657cde-3651-34c0-93fa-1e9cfccfafa2","inAppOwnershipType":"PURCHASED","signedDate":1688470718581,"environment":"Sandbox","transactionReason":"RENEWAL","storefront":"KOR","storefrontId":"143466"}},"hiveiap_receipt_start_date_ms":"1683534980000","hiveiap_receipt_expire_date_ms":"1683535160000","hiveiap_apple_info":{"original_transaction_id":"2000000287618347"},"hiveiap_iap_payload":"{\"server\":\"1\",\"character\":\"1\"}","hiveiap_receipt_cancel_date_ms":0,"hiveiap_receipt_refund_date_ms":0}' \
-H "Content-Type: application/json" \
https://sandbox-misample.com2us.net/hive/Iap_subscription_notification // (the API endpoint example provided from your game server)
curl -L -v
-d '{"notification_type":"13","hiveiap_market_id":2,"hiveiap_market_pid":"sub01","hiveiap_receipt_verify_result":{"kind":"androidpublisher#subscriptionPurchaseV2","startTime":"2023-07-25T08:00:19.285Z","regionCode":"KR","subscriptionState":"SUBSCRIPTION_STATE_EXPIRED","latestOrderId":"GPA.3319-2535-4331-99754..0","canceledStateContext":{"userInitiatedCancellation":{"cancelTime":"2023-07-25T08:07:21.881Z"}},"testPurchase":[],"acknowledgementState":"ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED","externalAccountIdentifiers":{"obfuscatedExternalAccountId":"84530982-c9c3-3114-b0dc-848dd7e8bf76"},"lineItems":[{"productId":"sub01","expiryTime":"2023-07-25T08:10:09.583Z","autoRenewingPlan":[],"offerDetails":{"basePlanId":"p1w"}}]},"hiveiap_receipt_start_date_ms":"1690272019000","hiveiap_receipt_expire_date_ms":"1690272609000","hiveiap_receipt_autoresume_date_ms":"","hiveiap_receipt_subscription_state":4,"hiveiap_google_info":{"purchase_token_hash":"5a109e5da69467a706a180fca423e09ab7671389","purchase_token":"eejgienjlbapbnojcnjipdib.AO-J1OxxtNGzvOT7-mSeeAORzZ0GZ90t33v7UQn-t4xPAPGLCQqQAPFmvDK3p3wO8ZwXfYCwmVk9pTI93P8k4IyZJn2XI7ES-EJEFPOLpmUzlXXsOndqbhu1oPRu7V4ddTIUCVB_cHjGKvRnZu1DUu2dEd603grO2Q","linked_purchase_token":"","linked_purchase_token_hash":""},"hiveiap_iap_payload":null,"hiveiap_receipt_cancel_date_ms":1690272441000,"hiveiap_receipt_refund_date_ms":0}' \
-H "Content-Type: application/json" \ (the API endpoint example provided from your game server)
- Request ( IAP > Game server)
| Field Name | Description | Type | Required |
| result_code | response code
| Integer | Y |
| result_msg | response message | String | Y |
- Response (Game server > IAP)
< HTTP/2 200
< server: nginx
< date: Fri, 25 Mar 2022 06:56:17 GMT
< content-type: application/json; charset=utf-8
{"result_code":0,"result_msg":"OK"}</pre>