Skip to content

PG payment

The following is the PG payment API that must be implemented by the game server to support PG payments in Windows OS games. For more details about PG payments in the Windows environment, please check here.

Payment completion history inquiry

Upon payment completion, the payment agency (PG) directly delivers the payment result to the Hive IAP v4 server. This method compensates for the instability of the network and prevents tampering with payment data. A cross-validation is performed by comparing the payment information registered during the preparation work with the information from the payment agency (PG). Once the integrity of the payment information is confirmed, additional safety measures are secured, and the payment information is stored. The stored payment information can be retrieved through the payment completion history inquiry API. At the time when the client needs the user's payment completion information, it requests the information from the game server, which retrieves the payment information through the Hive IAP v4 server. If the user's payment history exists, the payment information verification is conducted using purchase_bypass_info.

Request URL

Commercial 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 authentication key in the Hive console App Center > Project Management > Select Game Company > Game Details > Basic Information.

Request parameters

Name Type Required (Required: M, Optional: O) Description
appid String M ID registered and issued in Hive Console > App Center
market_id Number M Unique market ID (use fixed value 15)
server_id String M Game server distinction code where the payment occurred
user_id_type String M Hive user type (use fixed value player_id)
user_id Number M Hive user ID (player_id)

Response elements

Name Type Required (Required: M, Optional: O) Description
result Number M Response code (0: success)
result_msg String M Result message according to the response code
unconsumed_lists Object Array M
┕ market_pid String M Unique product ID
┕ order_id String M Order number
┕ server_id String M Distinction code for the game server the purchasing user accessed
┕ vid String M PlayerID of the purchasing user
┕ uid String O Hive membership UID of the purchasing user
┕ amount String M Payment amount
┕ currency String M Payment currency
┕ quantity Number M Purchase quantity
┕ started_datetime Datetime M Time when the payment started (Y-m-d H:i:s)
┕ paid_datetime Datetime M Time when the payment was completed (Y-m-d H:i:s)
┕ started_datetime_ms Number M Time when the payment started (Unix TimeStamp Milliseconds)
┕ paid_datetime_ms Number M Time when the payment was completed (Unix TimeStamp Milliseconds)
┕ hiveiap_receipt String M Encrypted HASH of payment information
┕ purchase_bypass_info String M Required information for receipt verification request
┕ iap_payload String O Additional information received from the client to send to the game server (in JSON String format)
(returns null if no information is received)

Request example

curl -L -v
 -d '{"appid" : "com.com2us.hivesdk.windows.microsoftstore.global.normal","market_id" : 15,"server_id" : "kr","user_id_type": "player_id", "user_id": 30000056996}' \
 -H "Content-Type: text/html" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed

Response example

{
    "result": 0,
    "result_msg": "SUCCESS",
    "unconsumed_lists": [
        {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
            "order_id": "h2164792542890731850",
            "server_id": "kr",
            "vid": "30000056996",
            "uid": "13079",
            "amount": "1200",
            "currency": "KRW",
            "quantity": 1,            
            "started_datetime": "2022-03-22 14:03:49",
            "paid_datetime": "2022-03-22 14:04:39",
            "market_id": "15",
            "hiveiap_receipt": "2YnGzfTCGycoMjcSyYyNXBjANwmFyB6m\/c0bYazQ8VQ=",
            "purchase_bypass_info": "eyJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2R...",
            "started_datetime_ms": 1647925429000,
            "paid_datetime_ms": 1647925479000,
            "iap_payload": null
        }
    ]
}

Payment information verification

The payment result verification API is based on IAP v4 receipt verification.

The payment result verification uses the purchase_bypass_info received earlier. The purchase_bypass_info contains various information received through the SDK before proceeding with the payment and is sent to Hive Analytics. If you need to send the sales log along with the receipt verification request, please use the game_info. The received game_info acts as a proxy for sending logs to the analytics server from Hive IAP.

Request URL

Production 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 authentication key found in the Hive console App Center > Project Management > Select Game Company > Game Details > Basic Information.

Request parameters

Name Type Required (Required: M, Optional: O) Description
purchase_bypass_info String M Data for receipt substitutes and analytics transmission
game_info Object Array O When there are logs to be sent to the game, such as game logs or sales logs, add this value to the game for transmission, and Hive IAP will act as an intermediary to send it to the analytics server. Since the item delivery completion (itemsendok) cannot be known during the receipt verification stage, this part must be implemented separately and provided as additional information.
⠀⠀server_uid bigint O user_id issued by the game server
If not, 0
⠀⠀giftee_uid bigint O null: Payment for personal use
0: There is a recipient but UID cannot be verified
⠀⠀level int O User's in-game level
Not necessary if there is no level. If not, 0.
⠀⠀character_id bigint O Unique character identifier value within the server
If there is no character concept, "0"
⠀⠀character_type_id int O Character type identifier value
Input "0" for games without a character concept
⠀⠀character_level int O Character type identifier value
Input "0" for games without a character concept
⠀⠀is_emulator int O Input "1" when accessing via PC emulator like BlueStacks, otherwise input "0"

Response elements

Name Type Required (Required: M, Optional: O) Description
result Number M Response code (Refer to Response Code)
result_msg String M Result message according to the response code
hiveiap_transaction_id String M Transaction ID generated for each validated receipt. This value is stored in the game server to perform duplicate receipt checks
hiveiap_market_id String O Unique market number (PG payment: fixed at 15)
hiveiap_market_pid String O Payment product PID
hiveiap_market_transaction_id String O Unique order number for the order
hiveiap_receipt String O Market receipt Object value (PG payment: fixed at null)
hiveiap_purchase_test String O Test payment status (Y: Test payment / N: Regular payment)
hiveiap_iap_payload String O Additional information received from the client to be sent to the game server. It is in JSON String format, and if no information is received, it returns null.

응답 코드

Code Message Comment
0 Success, Duplicate receipt Verification successful
1000001 No requested parameter When no parameters are sent
1000003 DB Connection Error When DB Connection fails
1000005 Internal Server Error Internal server error
1000006 The required parameter info is missing When the required parameter value is missing
1000503 Failed to authenticate the receipt Failed to verify the receipt or if it is a hacked receipt
(e.g., spoofing hack)
1000507 Failed to save the purchase info Failed to save purchase history
1000524 Failed to authenticate the receipt. (not exist order) Receipt verification failed (non-existent order)
1000525 Failed to authenticate the receipt. (wrong param) Receipt verification failed (parameter error)

Request example

curl -L -v 
 -d '{"purchase_bypass_info":"eyJtYXJrZXRfaWQiOiIxNSIsIm9yZGVyX2lkIjoiSDMxNjQ3OTI1NDI4OTA3MzE4NTAiLCJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2RrLndpbmRvd3MubWljcm9zb2Z0c3RvcmUuZ2xvYmFsLm5vcm1hbC5pdGVtMDEiLCJ2aWQiOiIzMDAwMDA1Njk5NiIsInVpZCI6IjEzMDc5Iiwic2VydmVyX2lkIjoia3IiLCJhcHBpZCI6ImNvbS5jb20ydXMuaGl2ZXNkay53aW5kb3dzLm1pY3Jvc29mdHN0b3JlLmdsb2JhbC5ub3JtYWwiLCJhbW91bnQiOiIxMjAwIiwic3RhcnRlZF9kYXRldGltZSI6bnVsbCwicGFpZF9kYXRldGltZSI6bnVsbCwiY3VycmVuY3kiOiJLUlciLCJoaXZlaWFwX3JlY2VpcHQiOiIyWW5HemZUQ0d5Y29NamNTeVl5TlhCakFOd21GeUI2bVwvYzBiWWF6UThWUT0ifQ=="}' 
 -H "Content-Type: text/html"
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify

Response example

{
    "result": 0,
    "result_msg": "success",
    "hiveiap_transaction_id": "HS_13",
    "hiveiap_market_id": 15,
    "hiveiap_market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "hiveiap_market_transaction_id": "h2164792542890731850",
    "hiveiap_receipt": null,
    "hiveiap_purchase_test": "N",
    "hiveiap_iap_payload": null
}

Payment result processing

Payment Result Processing API is based on IAP v4 Item Payment Result Transmission.

The payment processing API finalizes the payment process from item purchase to completion of delivery. If the payment processing is not completed, the user cannot purchase the same item. When attempting to purchase and entering the payment page, a message saying 'You already own this item.' will be displayed, and the payment will not proceed.

When attempting to purchase and pay by opening multiple payment windows, any products for which payment has not been processed will be automatically canceled. After processing all payment processes such as checking purchase limits and item delivery conducted by the game server, the payment result is sent to notify the Hive IAP v4 server that the payment has been completed. If you wish to request a payment cancellation, you can also request cancellation through the delivery result processing API.

Request URL

Production 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 authentication key found in the Hive console App Center > Project Management > Select Game Company > Game Details > Basic Information.

Request parameters

Name Type Required
(Required: M, Optional: O)
Description
hiveiap_transaction_id String M The hiveiap_transaction_id of the receipt verification result
result_status Number M Item delivery success status
0: Delivery failed
1: Delivery successful
2: Payment cancellation refund request (PG only)
result_status_message String O Reason for delivery failure or payment cancellation request
user_id_type String M Hive user type (fixed value player_id)
user_id Number M Hive user ID (player_id)
asset Object Array O Information about the delivered items
Values are only provided when delivery is successful, and an empty array ([]) is returned when delivery fails
⠀⠀asset_id String O Item ID
⠀⠀asset_name String O Item name
⠀⠀quantity Number O Number of delivered items

Response elements

Name Type Required
(Required: M, Optional: O)
Description
result Number M Response code (0: success)
result_msg String M Result message according to the response code

Request example

  • Call
curl -L -v
 -d '{"hiveiap_transaction_id" : "HS_13","result_status": 1,"user_id_type": "player_id","user_id": 30000056996,"asset": [ {"asset_id":"item_id","asset_name":"item_name","quantity":1}
,{"asset_id":"item_id","asset_name":"item_name","quantity":1}]}' \
 -H "Content-Type: text/html" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap.qpyou.cn/api_v4/item_result

Response example

{
    "result": 0,
    "result_msg": "success"
}

Payment result notification service

The payment result notification service sends the result to the game server immediately upon completion or cancellation of the payment. This API passes the purchase_bypass_info value just like the Get Purchase Result, allowing the game to use this value to verify the receipt and grant the item to the user. Receipt verification and item granting should only proceed if the type is paid in the Payment Result Transmission Information.

Note

To use this API, you must first set up a PG company in the Hive console. For receipt verification and product delivery, it is recommended to use either this API or the payment completion history inquiry API.

Basic information on payment result transmission

HTTPメソッド POST
コンテンツタイプ application/json
データ形式 JSON

Payment result transmission information

Name Type Required
(Required: M, Optional: O)
Description
type String M Notification type (paid: Payment completed, cancelled: Payment cancelled or refunded)
market_pid String M Unique product ID
order_id String M Order number
server_id String M Code distinguishing the game server the purchasing user accessed
vid String M PlayerID of the purchasing user
vid_type String O SDK version value: v4
uid String O Hive membership UID of the purchasing user
amount String M Payment amount
currency String M Payment currency
quantity Number M Purchase quantity
started_datetime Datetime M Time when the payment started (Y-m-d H:i:s)
paid_datetime Datetime M Time when the payment was completed (Y-m-d H:i:s)
cancelled_datetime Datetime O Time when the payment was cancelled or refunded (Y-m-d H:i:s)
started_datetime_ms Number M Time when the payment started (Unix TimeStamp Milliseconds)
paid_datetime_ms Number M Time when the payment was completed (Unix TimeStamp Milliseconds)
cancelled_datetime_ms Number O Time when the payment was cancelled or refunded (Unix TimeStamp Milliseconds)
cancelled_reason String O Reason for the payment cancellation or refund
hiveiap_receipt String M Encrypted HASH of payment information
purchase_bypass_info String M Required information for receipt verification request
iap_payload String O Additional information received from the client to be sent to the game server. It is in JSON String format, and returns null if no information is received.

Payment result transmission example (upon payment completion)

{
    "type": "paid",
    "market_id": "15",
    "order_id": "H2168993822440686730",
    "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "vid": "20000011337",
    "uid": "67200717",
    "vid_type": "v4",
    "server_id": "kr",
    "appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
    "amount": "1200",
    "started_datetime": "2023-07-21 20:17:06",
    "paid_datetime": "2023-07-21 20:18:13",
    "cancelled_datetime": null,
    "cancelled_reason": null,
    "currency": "KRW",
    "quantity": 1,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "started_datetime_ms": 1689938226000,
    "paid_datetime_ms": 1689938293000,
    "cancelled_datetime_ms": null,
    "iap_payload": null,
    "purchase_bypass_info": "eyJ0eXBlIjoicGFpZCIsIm1hcmtldF9pZCI6IjE1Iiwib3JkZXJfaWQiOi..."
}

Payment result transmission example (when payment is canceled)

{
    "type": "cancelled",
    "market_id": "15",
    "order_id": "H2168993822440686730",
    "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "vid": "20000011337",
    "uid": "67200717",
    "vid_type": "v4",
    "server_id": "kr",
    "appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
    "amount": "1200",
    "started_datetime": "2023-07-21 20:17:06",
    "paid_datetime": "2023-07-21 20:18:13",
    "cancelled_datetime": "2023-07-21 20:21:44",
    "cancelled_reason": "테스트 결제 취소",
    "currency": "KRW",
    "quantity": 1,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "started_datetime_ms": 1689938226000,
    "paid_datetime_ms": 1689938293000,
    "cancelled_datetime_ms": 1689938504000,
    "iap_payload": null,
    "purchase_bypass_info": "eyJ0eXBlIjoiY2FuY2VsbGVkIiwibWFya2V0X2lkIjoiMT..."
}