The web PG payment API is used when you want to implement PG payment feature on a website without using the Hive SDK billing in Windows app development. The web PG payment API is different from the API used to implement PG payment in an app.

Get Product List

Retrieve product information. This is used to implement the product list in an app.

Request URL

Environment URL
Production URL https://store.withhive.com/external/api/product
Sandbox URL https://sandbox-store.withhive.com/external/api/product
HTTP Method POST
Content-Type text/html; charset=utf-8
Data Format JSON
Authorization Bearer (token)

The Bearer token corresponds to the Hive Certification Key found in Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information.

Request Parameters

Field Type Required Description
api String O API identifier (use fixed value: product)
market_id String O Hive market ID (PG payment: use fixed value 15)
appid String O Hive AppID
hive_country String O Country code (ISO 3166-1 alpha-2)
game_language String O Language (ISO 639-1 alpha-2)
vid String O Hive account information (Player ID)
vid_type String O Account type (use v4 for new games)
market_pid_type String O Product type (consumable: use consumable)

Response Elements

Field Type Required Description
result Integer O Response code (0 for success, others for error)
result_msg String O Response message
product_list Object O List of product information
product_list > market_pid String O Product PID
product_list > price Int O Product price (numeric value)
product_list > currency String O the currency of product price
product_list > display_price String O Product price (including currency symbol)
product_list > title String O Product name
product_list > description String O Product description
product_list > product_type String O Product type (consumable: use consumable)
update_date String O Date and time of the last update for the product PID information

Request Example

Response Example

Request Product Order

Request a product order, selected from the product list, using the PID (product ID) information.

Request URL

Environment URL
Production URL https://store.withhive.com/external/api/order
Sandbox URL https://sandbox-store.withhive.com/external/api/order
HTTP Method POST
Content-Type text/html; charset=utf-8
Data Format JSON
Authorization Bearer (Token)

The Bearer token corresponds to the Hive Certification Key found in Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information.

Request Parameters

Field Type Required Description
market_id String O Hive Market ID
appid String O Hive AppID
hive_country String O Country code (ISO 3166-1 alpha-2)
game_language String O Language (ISO 639-1 alpha-2)
vid String O Hive Account Information (Player ID)
vid_type String O Account type (v4 for new games)
market_pid String O Product PID
server_id String O Server ID
os String O Window: W, MAC: M, Android: A
iap_payload String X Purchase metadata defined by the app developer

Request Example

Response Example

If the product order request is processed successfully, a popup window for selecting the payment method is returned. The HTML page that constructs the following popup window will be returned.

Searching payment completion history

Upon payment completion, the PG company delivers the payment result directly to the Hive IAP v4 server. This method compensates for network insecurity and prevents the forgery of payment data. Also, the PG company compares the information registered when pre-working and of PG company to cross-check. If you have confirmed the integrity of the payment information, make sure to be more secure and save the payment information. You can search the payment information saved through the searching payment completion history API.
If needed the user’s payment completion information, the client requests to the game server, and the game server search the payment information through the Hive IAP v4 server. If there is the user’s payment history, you can verify the payment information with purchase_bypass_info.

Request URL

    Common URL https://hiveiap.qpyou.cn/api_v4/purchases/unconsumed
    Sandbox URL https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed
    HTTP Method POST
    Content-Type application/json
    Data Format JSON
    Authorization Bearer (token)

The Bearer token corresponds to the Hive Certification Key found in Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information.

Request Parameters

    Name Type Required
    (Y/N)    		 Description
    appid String Y ID registered and issued on Hive Console > AppCenter
    market_id Number Y Unique market ID (15 fixed)
    server_id String Y Identification code of game server that payment occurred
    user_id_type String Y Hive user type
    uid : C2S module(v0)
    vid : Auth v1(v1)
    player_id : Auth v4(v4)
    user_id Number Y Hive user ID
    Sent according to user_id_type
    uid : C2S module(v0)
    vid : Auth v1(v1)
    player_id : Auth v4(v4)

Response Elements

    Name Type Required
    (Y/N)    		 Description
    result Number Y Response code (0: Success)
    result_msg String Y Result message according to the response code
    unconsumed_lists Object Array Y
    ┕ market_pid String Y Item’s unique ID
    ┕ order_id String Y Order number
    ┕ server_id String Y Identification code of game server that the purchaser accessed
    ┕ vid String Y PlayerID of the purchaser. VID in the case of Authentication v1
    ┕ uid String N UID of purchaser
    ┕ amount String Y Amont of payment
    ┕ currency String Y Payment currency
    ┕ started_datetime Datetime Y Time to start payment (Y-m-d H:i:s)
    ┕ paid_datetime Datetime Y Time to complete payment (Y-m-d H:i:s)
    ┕ hiveiap_receipt String Y A cryptographic hash of the payment info
    ┕ purchase_bypass_info String Y Required info for requesting a receipt verification
    ┕ additionalInfo String N Additional information sent from client to game server (JSON String format)
    (Return null if there’s no received information)

Request Example

Response Example

Verifying payment info

Verifying payment results API is based on Hive IAP v4 Verifying Receipt API.

To verify payment results, you need to use purchase_bypass_info received before. purchase_bypass_info includes various data passed through Hive SDK before processing payment, and is sent to Hive Analytics. Also, you can use game_info if you need to send the revenue log with the request of verifying receipts, and the game_info transmits logs from Hive IAP to the Hive Analytics server.

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
    Content-Type text/html
    Data Format JSON
    Authorization Bearer (token)

The Bearer token corresponds to the Hive Certification Key found in Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information.

Request Parameters

    Name Type Required
    (Y/N)    		 Description
    purchase_bypass_info String Y Data of receipts substitute and for transmitting to Hive Analytics
    game_info Object Array N 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. The following items should be filled for Analytics level index basically provided by BI.
    ⠀⠀server_uid bigint N User identifier used in game server. Set as 0 if the value does not exist
    ⠀⠀giftee_uid bigint N 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)
    ⠀⠀Level int N The level of user in the game
    (Not required if level does not exist). Set as 0 if level does not exist
    ⠀⠀character_id bigint N Character identifier used in server (Pk?)
    Set this identifier as 0 if the game has no character
    ⠀⠀character_type_id int N The value of character type used in server
    Set this value as 0 if the game has no character
    ⠀⠀character_level int N The value of character type used in server
    Set this value as 0 if the game has no character
    ⠀⠀is_emulator int N If connecting with Emulator for PC such as BlueStacks, return 1; unless, return 0

Response Elements

    Name Type Required
    (Y/N)    		 Description
    result Number Y Response code (See Response Code)
    result_msg String Y Result message according to the response code
    hiveiap_transaction_id String Y Transaction ID created by receipts verified successfully
    Save this value on the game server, and the game checks if the receipt is duplicated.
    hiveiap_market_id String N Unique market number (PG payment: 15 fixed)
    hiveiap_market_pid String N Purchased item’s PID
    hiveiap_market_transaction_id String N Unique order number about the order
    hiveiap_receipt String N Object value on market receipts (PG payment: null fixed)
    hiveiap_purchase_test String N Whether to test payment (Y: Test payment / N: Common payment)

Response Code

    Code Message Comment
    0 Success, Duplicate receipt
    1000001 No requested parameter
    1000003 DB Connection Error
    1000005 Internal Server Error
    1000006 The required parameter info is missing
    1000503 Failed to authenticate the receipt e.g., Spoofing hack
    1000507 Failed to save the purchase info
    1000524 Failed to authenticate the receipt. (not exist order)
    1000525 Failed to authenticate the receipt. (wrong param)

Request Example

Response Example

Handling item delivery results

Item Delivery Result API is based on Hive IAP v4 Verifying Receipt.

Item Delivery Result API completes payment by proceeding with all payment steps, from purchasing an item to completing the payment.
If the payment has not been completed, purchasing the same item is unavailable, and the ‘This item is already owned.’ message is displayed and the payment proceeds failed even if you attempt to purchase and enter the billing page.

All items that have not been completed payment will be automatically canceled even by trying to purchase or pay on multiple billing windows. The game server notifies the Hive IAP v4 server that the payment has been completed by sending the payment result after processing all payment processes such as checking the purchase limit and item payment. Item Delivery Result API is also available to cancel the payment.

Request URL

    Common URL https://hiveiap.qpyou.cn/api_v4/item_result Sandbox URL https://sandbox-hiveiap.qpyou.cn/api_v4/item_result HTTP Method POST Content-Type text/html Data Format JSON Authorization Bearer (token)

The Bearer token corresponds to the Hive Certification Key found in Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information.

Request Parameters

    Name Type Required
    (Y/N)    		 Description
    hiveiap_transaction_id String Y hiveiap_transaction_id of the receipt verification result
    result_status Number Y Whether success in item delivery or not
    0: Delivery failure
    1: Delivery success
    2: Request payment cancel/refund (only for PG payment)
    result_status_message String N Reason for the delivery failure or the payment cancelation request
    user_id_type String Y Hive user type
    v0: C2S module (uid)
    v1: Auth v1 (vid)
    v4: Auth v4 (player_id)
    user_id Number Y User ID
    If user_id_type is v0, send uid; if v1, send vid; if v4, send player_id
    asset Object Array N The delievered item data
    Send the value with delivery success, and an empty array ([]) response with delivery failure
    ⠀⠀asset_id String N Item ID
    ⠀⠀asset_name String N Item name
    ⠀⠀quantity Number N The number of delivered item

Response Elements

    Name Type Required
    (Y/N)    		 Description
    result Number Y Response code (0: Success)
    result_msg String Y Result message according to the response code

Request Example

Response Example

Notifying payment completion

When a payment is made or cancelled, the payment notification service immediately transmits the result to your game server.
This API returns purchase_bypass_info like Searching payment completion history API, so you can verify purchase receipt and give items to the user with this API.
You should proceed with receipt verification and transmitting item only when the type in Transmitting payment results information is “paid.”

Transmitting payment results basics

    HTTP Method POST
    Content-Type application/json
    Data Format JSON
    Authorization Bearer (token)

The Bearer token corresponds to the Hive Certification Key found in Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information.

Transmitting payment results information

    Name Type Required
    (Y/N)    		 Description
    type String M notification type(paid: paid purchase, cancelled: canceled or refunded purchase)
    market_pid String Y Item’s unique ID
    order_id String Y Order no.
    server_id String Y Identification code of game server that the purchaser accessed
    vid Number Y PlayerID of the purchaser. VID in the case of Authentication v1
    vid_type String O the vid type value per SDK version(“v4” by default)
    uid Number N UID of purchaser
    amount String Y Amont of payment
    currency String Y Payment currency
    started_datetime Datetime Y Time to start payment (Y-m-d H:i:s)
    paid_datetime Datetime M Time a payment is completed (Y-m-d H:i:s)
    cancelled_datetime Datetime O Time a payment is canceled or refunded (Y-m-d H:i:s)
    cancelled_reason String O Reason a payment is canceled or refunded
    hiveiap_receipt String Y A cryptographic hash of the payment info
    purchase_bypass_info String Y Required info for requesting a receipt verification
    additionalInfo String O The additional information received from the client, which is to be sent to the game server. It is in JSON String format and returned as null if no information received.

Example of transmitting payment results (payment completed)

Example of transmitting payment results (payment canceled or refunded)