Web PG payment

The web PG payment API is an API used when you want to implement PG payments on a website, although it does not use the Hive SDK billing when developing Windows apps. The web PG payment API is different from the API that implements PG payments in the app.

Product list inquiry¶

Retrieves product information. Used to implement the product list in the app.

Request URL¶

The Bearer token corresponds to the Hive authentication key in App Center > Project Management > Select Game Company Game > Game Details > Basic Information in the Hive Console.

Request parameters¶

Response elements¶

Request Example¶

curl -L -v \
    -d '{"api": "product","market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid_type": "consumable"}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/product

Response example¶

{
    "result": 0,
    "result_msg": "success",
    "product_list": [
        {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
            "price": 1200,
            "currency": "KRW",
            "display_price": "₩1,200",
            "title": "크리스탈 한 줌",
            "description": "크리스탈 한 줌",
            "product_type": "consumable"
        }, {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item02",
            "price": 2500,
            "currency": "KRW",
            "display_price": "₩2,500",
            "title": "크리스탈 묶음",
            "description": "크리스탈 묶음",
            "product_type": "consumable"
        }, {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item03",
            "price": 3900,
            "currency": "KRW",
            "display_price": "₩3,900",
            "title": "크리스탈 더미",
            "description": "크리스탈 더미",
            "product_type": "consumable"
        }
    ],
    "update_date": "2022-10-28 16:11:23"
}

Product order request¶

Requests a product order using the PID (Product ID) information selected from the product list.

Request URL¶

The Bearer token corresponds to the Hive authentication key in App Center > Project Management > Select Game Company Game > Game Details > Basic Information in the Hive Console.

Request parameters¶

Request Example¶

curl -L -v \
    -d '{"market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01","server_id": "KR1","os": "A","quantity": 1,"iap_payload": "{\"character_id\":\"hivesdk01\"}"}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/order

Response example¶

When the product order request is processed successfully, it returns a popup window to select the payment method. Below is the HTML page that makes up the popup window.

Payment completion details inquiry¶

When the payment is completed, the payment agency (PG) directly transmits the payment result to the Hive IAP v4 server. This method compensates for the instability of the network and prevents tampering with payment data. During pre-work, a cross-validation is performed by comparing the registered payment information with the information of 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.

The client requests information from the game server at the point when the user's payment completion information is needed, and the game server retrieves the payment information through the Hive IAP v4 server. If there is a record of the user's payment, the payment information verification is carried out using purchase_bypass_info.

Request URL¶

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

Request parameters¶

Name	Type	Required (Required: M, Optional: O)	Description
appid	String	M	ID registered and issued from Hive console > App Center
market_id	Number	M	Unique market ID (use fixed value `15`)
server_id	String	M	Game server identification code where the payment occurred
user_id_type	String	M	HIVE user type uid : Individual module (v0) vid : Authentication v1 (v1) player_id : Authentication v4 (v4)
user_id	Number	M	HIVE user ID sent according to user_id_type uid : Individual module (v0) vid : Authentication v1 (v1) player_id : Authentication v4 (v4)

Response elements¶

Name	Type	Required (Required: M, Optional: O)	Description
result	Number	M	Response code (0: success)
result_msg	String	M	Result message based on the response code
unconsumed_lists	Object Array	M
┕ market_pid	String	M	Product unique ID
┕ order_id	String	M	Order number
┕ server_id	String	M	Code distinguishing the game server the user purchased from
┕ vid	String	M	User's PlayerID, VID for v1 authentication
┕ uid	String	O	User's uid
┕ amount	String	M	Payment amount
┕ currency	String	M	Payment currency
┕ quantity	Number	M	Purchase quantity
┕ started_datetime	Datetime	M	Time payment started (Y-m-d H:i:s)
┕ paid_datetime	Datetime	M	Time payment completed (Y-m-d H:i:s)
┕ started_datetime_ms	Number	M	Time payment started (Unix TimeStamp Milliseconds)
┕ paid_datetime_ms	Number	M	Time payment completed (Unix TimeStamp Milliseconds)
┕ hiveiap_receipt	String	M	Payment information encryption HASH
┕ 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, use the game_info. The received game_info acts as an intermediary 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 in App Center > Project Management > Select Game Company Game > Game Details > Basic Information in the Hive Console.

Request parameters¶

Name	Type	Required (Required: M, Optional: O)	Description
purchase_bypass_info	String	M	Data for receipt substitute and analytics transmission
game_info	Object Array	O	If 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 agent to send it to the analytics server. In the receipt verification stage, it is not possible to know whether the item has been delivered (itemsendok), so 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: The recipient exists but UID cannot be verified; Derby Days guest accounts do not have a hub guest account, so this applies here
⠀⠀level	int	O	User's in-game level Not needed if there is no level. If not, 0.
⠀⠀character_id	bigint	O	A unique character identifier within the server (PK?). If there is no character concept, "0"
⠀⠀character_type_id	int	O	Character type identifier For games without a character concept, input "0"
⠀⠀character_level	int	O	Character type identifier For games without a character concept, input "0"
⠀⠀is_emulator	int	O	If accessed via an emulator for PC, such as BlueStacks, input "1"; 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 should be stored on the game server to perform duplicate receipt checks.
hiveiap_market_id	String	O	Market unique 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)

Response Code¶

Code	Message	Comment
0	Success, Duplicate receipt	Verification successful
1000001	No requested parameter	When there are no parameters 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 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"
}

Payment result processing¶

Payment Result Processing API is based on IAP v4 Item Payment Result Transmission. The Payment Result Processing API finalizes the payment process from item purchase to payment completion. If the payment process is not completed, the user cannot purchase the same product. When attempting to purchase and entering the payment page, a message saying 'You already own this product.' 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 procedures, 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.

요청 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 in App Center > Project Management > Select Game Company Game > Game Details > Basic Information in the Hive Console.

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 succeeded 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 v0: Individual module (uid) v1: Authentication v1 (vid) v4: Authentication v4 (player_id)
user_id	Number	M	User ID If user_id_type is v0, send uid; if v1, send vid; if v4, send player_id
asset	Object Array	O	Information of the delivered item Only provide values when delivery is successful, and respond with an empty array ([]) when delivery fails
asset_id	String	O	Item ID
asset_name	String	O	Item name
⠀⠀quantity	Number	O	Number of items delivered

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

요청 예시¶

curl -L -v
 -d '{"hiveiap_transaction_id" : "HS_13","result_status": 1,"user_id_type": "vid","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 when a payment is completed or canceled. This API transmits the purchase_bypass_info value in the same way as the payment completion history inquiry, allowing the game to use this value to verify the receipt and grant the product to the user. Receipt verification and product granting should only be performed when the type in the payment result transmission information is paid.

Payment Result Transmission Basic Information¶

HTTP Method	POST
Content-Type	application/json
Data Format	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	Player ID of the purchasing user, VID for v1 authentication
vid_type	String	O	vid type value according to SDK version (default v4)
uid	String	O	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 payment started (Y-m-d H:i:s)
paid_datetime	Datetime	M	Time payment completed (Y-m-d H:i:s)
cancelled_datetime	Datetime	O	Time payment was cancelled or refunded (Y-m-d H:i:s)
started_datetime_ms	Number	M	Time payment started (Unix TimeStamp Milliseconds)
paid_datetime_ms	Number	M	Time payment completed (Unix TimeStamp Milliseconds)
cancelled_datetime_ms	Number	O	Time payment was cancelled or refunded (Unix TimeStamp Milliseconds)
cancelled_reason	String	O	Reason for 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 send to the game server. It is in JSON String format, and if no information is received, it returns null.

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

Refund user re-payment target Refund History Inquiry API¶

This API retrieves the refund history for users who have requested a refund and need to make a re-payment.
If you have activated the re-payment feature for refunded users in your self-implemented web store, you need to implement the re-payment notification popup UI for refunded users using the response value of the 'Refund User Re-Payment Target Refund History Inquiry' API.

When using the 'Refund user ee-payment target Refund History Inquiry' API, please be aware of the following.

• The is_refund field in the response items of the PlayerID Lookup API can only be used when it is true.
• When requesting payment for a re-payment case, the request parameter json must include refund_idx(Integer) and is_repayment(Integer) as required fields.

Request URL¶

The Bearer token corresponds to the Hive authentication key in App Center > Project Management > Select Game Company Game > Game Details > Basic Information in the Hive Console.

Request parameters¶

Response elements¶

Request example¶

curl -L -v \
        -d '{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","vid_type":"v4","vid":"20000015900","game_language":"ko","device":"pc"}' \
        -H "Content-Type: text/html" \
        -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
        https://sandbox-store.withhive.com/external/api/refund_info

Response example¶

{
    "result": 0,
    "result_msg": "success",
    "guide_title": "환불 상품 재결제 안내",
    "guide_content": "고객님의 계정은 게임 서비스 약관 및 운영 정책 위반 행위(결제시스템 악용)가 확인되어, 
    게임 이용이 제한되었습니다.\n\n알 수없는 이유로 결제가 취소되었거나, 혹은 비정상적인 절차로 환불된 상품의 경우, 동일 상품 재결제 후 게임 이용이 가능합니다.\n\n 현재 접속한 단말OS의 마켓 상품만 재결제가 가능하오니, 다른 마켓은 해당 앱으로 접속하여 재결제 부탁드립니다. 
    스팀 환불 내역에 대한 재결제는 PC에서 진행하세요. 모든 마켓의 취소/환불 상품의 재결제가 완료되어야 게임 이용이 가능합니다.\n\n일부 마켓에서 한 상품을 여러 수량으로 한 번에 구매 후 환불한 경우, 
    동일한 수량으로 재결제 해야 합니다. 만약 환불한 수량과 재결제한 수량이 일치하지 않으면 해당 재결제 건은 자동 취소됩니다. 
    취소되는 시점은 마켓에 따라 상이하며 수일이 걸릴 수 있습니다.\n\n 재결제 도중 오류로 인하여 결제 실패한 경우, 현재 계정으로 다시 게임을 재실행해주세요. 디바이스를 변경하여 동일한 마켓계정이면서 다른 게임 계정으로 로그인하시면 결제가 정상적으로 완료되지 않을 수 있습니다.\n\n결제 불가상품을 비롯한 그밖의 문의사항은 고객센터로 접수 부탁드립니다.\n\n* 환불 시간은 UTC+9 기준입니다.",
    "customer_site": {
        "pc": "https://sandbox-customer.withhive.com/com2us/faq/game/539",
        "mobile": "https://sandbox-customer-m.withhive.com/com2us/faq/game/539"
    },
    "refund_list": [
        {
            "refund_idx": 20850,
            "market_id": 1,
            "market_pid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01",
            "refund_time": "2023.02.02 15:47 (UTC+9)",
            "refund_time_ms": 1675320475000,
            "quantity": 1
        }
    ]
}

Example of re-payment guide popup for refund user¶