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 Hive 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, Hive IAP sends notifications to all game servers.

 

Hive 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 (Hive 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

    		 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
    		 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 (Hive IAP > Game server)
    Apple App Store

    Google Play Store

  • Request (Hive IAP > Game server)
    Apple App Store

    Google Play Store

     

  • Response Specification (Game server > Hive IAP)
    Field Name Description Type Required
    result_code response code

    • 0: Application success. Respond as a success unless game server error
    • Other codes: Application failure
    		 Integer Y
    result_msg response message String Y
  • Response (Game server > Hive IAP)