IAP v4 notifying real-time subscription

Real-time subscription notification helps your game implement diverse types of subscription such as in grace period, on hold, and paused by receiving subscription state. The real-time subscription notification API is called from the IAP server side and it will send request to your game server. It will deliver the status change of the user subscription via the request body of this API in real-time. Therefore, your game server shoud provide an API endpoint (URL) to receive this information to the Hive Server.

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 Apple App Store 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 Active In grace period On hold Paused 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_token` field (sha1). Due to long length of `purchase_token` value, 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_token` field (sha1). Due to long length of `linked_purchase_token` value, 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: text/html" \
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: text/html" \ (the API endpoint example provided from your game server)

• Request ( IAP > Game server)

> POST /hive/Iap_subscription_notification HTTP/2
> Host: misample.com2us.net // (the API endpoint example provided from your game server)
> user-agent: curl/7.68.0
> accept: /> content-type: text/html
> content-length: 1211

> POST /hive/Iap_subscription_notification HTTP/2
> Host: misample.com2us.net // (the API endpoint example provided from your game server)
> user-agent: curl/7.68.0
> accept: /> content-type: text/html
> content-length: 1369

• 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>