The following is the PG payment API that your game server should use to support PG payments for the games on Windows OS. For details about PG payments on Windows OS, see the following.

1. 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
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)
Error code
  • Call
  • Request
  • Response

2. 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
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)
Error code
  • Call
  • Request
  • Response

3. 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
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
Error code
  • Call
  • Request
  • Response

4. 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
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)