Receipt Verification API performs validation on the in-app purchased receipt and then responds with the verification result as to whether the receipt is processed normally. Since hiveiap_transaction_id of the response value is a unique ID issued to each receipt, it is stored on the game server and the item is paid after checking whether the receipt is duplicated.
If you use Hive IAP v4 Receipt Verification API and transfer all values of all Request parameters, sales data and game data about sales information are transmitted by Hive IAP. Additionally, you are not required to develop the API for payment search on Hive One integrated search in games respectively.

  • Request URL
    Common URL https://hiveiap-verify.qpyou.cn/api_v4/verify
    Sandbox URL https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify
    HTTP Method POST
    HTTP Header Content-Type text/html
    Authorization Bearer (Optional)

    • You can use a Bearer token only if the Hive Certification Flag at Hive Console AppCenter > Game Management > Game List: Select your company’s game > Game Details > Basic Info is set to Y.
    • The Bearer token is the Hive Certification Key at AppCenter > Game Management > Game List: Select your company’s game > Game Details > Basic Info.
    Data Format JSON
  • Request
    Field Name Description Type Required
    purchase_bypass_info Purchaser, device and receipt information extracted by Hive SDK.
    When implementing Hive IAP v4 in-app purchase, bypassInfo (the value encoded to Base64 with JSON format) from IAPV4Receipt Object is sent from Hive SDK v4 to Game Client → Game Server → Hive IAP v4 Receipt Verification Server in order. The object is a callback of Purchase() or Restore() method from IAPV4 Class, Hive SDK v4    		 String Y
    market_id Market ID (Apple App Store: 1, Google Play Store: 2, Lebi: 3, ONE Store: 4) (deprecated with Hive SDK v4.6.0 and later) Integer Y
    appid APPID (deprecated with Hive SDK v4.6.0 and later) String Y
    appversion APP VERSION (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    did Device ID of purchaser (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    hive_country Country code distinguished by the IP sent from Hive SDK. ISO 3166-1 (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    country Country code on user device (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    client_ip Device IP of purchaser (for sending Analytics) String N
    language Language code on user device. ISO 639-1 Alpha-2 (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    game_language Language code selected by user in game. ISO 639-1 Alpha-2 (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    vid PlayerID of the purchaser. VID in the case of Authentication v1 (deprecated with Hive SDK v4.6.0 and later) String Y
    uid UID of purchaser (deprecated with Hive SDK v4.6.0 and later) String N
    server_id Server ID for distinguish which game server user accesses (deprecated with Hive SDK v4.6.0 and later) String N
    device_model Device model of purchaser (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    os_version OS version on the device of purchaser (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    sdk_version The version of Hive SDK applied for the game (for sending Analytics) (deprecated with Hive SDK v4.6.0 and later) String N
    hiveiap_receipt Receipt data delivered from a market. Use the value of hiveiapReceipt field in the IAPV4Receipt object, responded to the callback from hive.IAPV4.purchase() (deprecated with Hive SDK v4.6.0 and later) String Y
    price The amount of purchase. Use the value of price field in the IAPV4Product, IAPV4Receipt object, responded to the callback from hive.IAPV4.purchase() (deprecated with Hive SDK v4.6.0 and later) Double Y
    currency Currency code for the purchase. Use the value of currency field in the IAPV4Product, IAPV4Receipt object, responded to the callback from hive.IAPV4.purchase() (deprecated with Hive SDK v4.6.0 and later) String Y
    game_info Game log. This value is sent by Hive IAP on behalf, so you are not required to send the game data about in-app purchase to Analytics respectively
    Since you can not get the result of item delivery when verifying receipt, this field needs to be implemented separately and then offered as an additional information. (Hive IAP v4 Transmitting Item Delivery Result)The following items should be filled for Analytics level index basically provided by BI.

    server_uid User identifier used in game server. Set as 0 if the value does not exist bigint
    giftee_uid null – not for a gift (normal purchase), 0 – receiver with unknown uid (e.g., guest account in derbydays which hub guest account does not exist) bigint
    level The level of user in the game (Not required if level does not exist). Set as 0 if level does not exist int
    character_id Character identifier used in server
    Set this identifier as 0 if the game has no character    		 bigint
    character_type_id The value of character type used in server
    Set this value as 0 if the game has no character    		 int
    character_level Character level used in server
    Set this level as 0 if the game has no character    		 int
    is_emulator If connecting with Emulator for PC such as BlueStacks, return 1; unless, return 0 int
    server_type A game server environment
    e.g., qa, dev, staging, production
    (The env column passes as "TEST" if server_type passes a value other than production on sending the purchase log to Hive Analytics v2.)    		 String

    ObjectN

  • Response
    Field Name Description Type Required
    result Response code.

    • 0: Verification success
      If the value of hiveiap_purchase_cancel_state field is 0 (purchase in progress) when the response code is 0 (Verification success), finish the market transaction after sending items.
      If the value of hiveiap_purchase_cancel_state field is 1 (purchase canceled) when the response code is 0, finish the market transaction without sending items.
    • 1000503: Verification failure (due to hacking or receipt counterfeit. Market is recommended to finish the transaction without sending items.)
    • 1000519: The receipt sent as pending state when user attempts a slow payment such as payment at CVS (added from Hive SDK v4.12.0). As its state is prior to pay, nothing is processed. Completion receipt is sent after success in payment.
    • Others: Errors from Hive IAP Verification server or market verification server. Process as Restore.
    		 Integer Y
    result_msg Response message String Y
    hiveiap_transaction_id Transaction ID generated by receipt succeeded verification. This value is saved in game server to check the duplicate receipt.
    Deliver only when the response code is 0 (Verification success)    		 String N
    hiveiap_receipt The value which converts the String-format receipt to Object. Apple App Store is unavailable to generate the object format, so it only receives as String.
    Deliver only when the response code is 0 (Verification success)    		 Apple App Store: String
    Others: Object    		 N
    hiveiap_receipt_verify_result Receipt verification result delivered by the market verification server. The value is transmitted only when the response code is 0 (verification successful).

    ※ The result may vary depending on the addition or change of the market verification server.
    The results should be used for reference purposes only and should not be used to determine the success/failure of payment of goods or items.

    		 Object N
    hiveiap_market_pid Market PID extracted from the receipt or the verification result of the receipt.
    Item is given to users based on the value of hiveiap_market_pid field. Make sure not to use the Market PID sent from the SDK as a callback due to the danger of memory transformation. Deliver only when the response code is 0 (verification success)    		 String N
    hiveiap_market_id Market code which distinguishes the store user paid.
    1: Apple App Store
    2: Google Play Store
    3: HIVE Lebi
    4: ONE store
    Deliver only when the response code is 0 (verification success)    		 Integer N
    hiveiap_purchase_cancel_state Whether to cancel a purchase or not. (0: purchase in progress, 1: purchase canceled)
    Only Apple App Store and ONE store are available to check the cancellation status. Deliver only when the response code is 0 (verification success)    		 Integer N
    hiveiap_quantity the quantity of items purchased Integer N
    hiveiap_iap_payload the purchase meta information defined by the game studio String N
  • Result code
    Code Message Comment
    0 Success, Duplicate receipt Verification success.
    1000001 No requested parameter When sent parameter does not exist.
    1000003 DB Connection Error When DB connection is failed.
    1000005 Internal Server Error Internal server error.
    1000006 The required parameter info is missing When essential parameter is null.
    1000503 Failed to authenticate the receipt When receipt verification is failed or it is a hacked receipt (spoofing).
    When the restore list includes the refund repayment receipt that no needs to deliver an item
    1000504 The Google public key hasn’t been registered When License Key for receipt verification on Google Play is not registered.
    1000505 The One Store appid hasn’t been registered When Market AppID for receipt verification on ONE Store is not registered.
    1000507 Failed to save the purchase info When failed to save the history of purchase.
    1000512 Failed to authenticate the productId. Product verification failure (when the purchased product information and the market receipt information do not match or do not exist.)
    1000516 The receipt verify server is abnormal When access to receipt verifying server is unavailable.
    1000519 Pending state Receipt The receipt sent as pending state when user prompt a slow payment such as payment at CVS. As its state is prior to pay, nothing is processed.
    1000520 Failed to authenticate the API Key. Failed to authenticate the Bearer token issued at Hive Console AppCenter.
    1000522 The Galaxy Store secret hasn’t been registered. When a secret key of Galaxy Store is not registered.
    1000523 Failed to authenticate the receipt. (unexpected system error from Samsung IAP Server) When failed to authenticate the receipt because of an unexpected system error from Samsung IAP Server.
    1000524 Failed to authenticate the receipt. (not exist order) When failed to authenticate the receipt because the order is not exist.
    1000525 Failed to authenticate the receipt. (wrong param) When failed to authenticate the receipt because of a wrong parameter.
    1000540 App Store Connect information not found. When not registered App Store Connect API information
  • Call Sample
    Apple(StoreKit1)

    Apple(StoreKit2)

    Google

    Hive Lebi

    ONE store

    Galaxy Store

    Facebook

    Huawei

    VIVO

    OPPO

    XIAOMI

  • Request Sample
    Apple(StoreKit1)

    Apple(StoreKit2)

    Google

    Hive Lebi

    ONE store

    Galaxy Store

    Facebook

    Huawei

    VIVO

    OPPO

    XIAOMI

  • Response Sample
    Apple(StoreKit1)

    Apple(StoreKit2)

    Google

    Hive Lebi

    ONE store

    Galaxy Store

    Facebook

    Huawei

    VIVO

    OPPO

    XIAOMI