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¶
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..."
}