Skip to content

PG payment

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.

Searching payment completion history

Upon payment completion, the PG company delivers the payment result directly to the 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 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 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 SDK user type uid : C2S module(v0) vid : Auth v1(v1) player_id : Auth v4(v4)
    user_id Number Y Hive SDK 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
    ┕ quantity Number Y Purchase quantity
    ┕ 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

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...",
            "additionalInfo": null
        }
    ]
}

Verifying payment info

Verifying payment results API is based on 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 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 IAP to the 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 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 Analytics
    game_info Object Array N Game log. This value is sent by 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

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

Handling item delivery results

Item Delivery Result API is based on 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 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 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 SDK 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

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

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.”

Note

To use this API, you first should setup PG Company in Hive Console.
For receipt verification and handing out items, it is recommended to use either this API or Searching payment completion history API, not both of them.

Transmitting payment results basics

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

The Bearer token corresponds to the 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
quantity Number Y Purchase quantity
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)

{
    "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,    
    "additionalInfo": null,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "purchase_bypass_info": "eyJ0eXBlIjoicGFpZCIsIm1hcmtldF9pZCI6IjE1Iiwib3JkZXJfaWQiOiJIMjE2ODk5MzgyMjQ0MDY4NjczMCIsIm1hcmtldF9waWQiOiJjb20uY29tMnVzLmhpdmVzZGsud2luZG93cy5taWNyb3NvZnRzdG9yZS5nbG9iYWwubm9ybWFsLml0ZW0wMSIsInZpZCI6IjIwMDAwMDExMzM3IiwidWlkIjoiNjcyMDA3MTciLCJ2aWRfdHlwZSI6InY0Iiwic2VydmVyX2lkIjoia3IiLCJhcHBpZCI6ImNvbS5jb20ydXMuaGl2ZXNkay53aW5kb3dzLm1pY3Jvc29mdHN0b3JlLmdsb2JhbC5ub3JtYWwiLCJhbW91bnQiOiIxMjAwIiwic3RhcnRlZF9kYXRldGltZSI6IjIwMjMtMDctMjEgMjA6MTc6MDYiLCJwYWlkX2RhdGV0aW1lIjoiMjAyMy0wNy0yMSAyMDoxODoxMyIsImNhbmNlbGxlZF9kYXRldGltZSI6bnVsbCwiY2FuY2VsbGVkX3JlYXNvbiI6bnVsbCwiY3VycmVuY3kiOiJLUlciLCJhZGRpdGlvbmFsSW5mbyI6bnVsbCwiaGl2ZWlhcF9yZWNlaXB0IjoidEpwd1FTSWxORmlDU1Bva0hTUllUdlRMbXRiRGlTWm5rWWE3K0lXYU13TT0ifQ=="
}

Example of transmitting payment results (payment canceled or refunded)

{
    "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": "network error",
    "currency": "KRW",
        "quantity": 1, 
    "additionalInfo": null,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "purchase_bypass_info": "eyJ0eXBlIjoiY2FuY2VsbGVkIiwibWFya2V0X2lkIjoiMTUiLCJvcmRlcl9pZCI6IkgyMTY4OTkzODIyNDQwNjg2NzMwIiwibWFya2V0X3BpZCI6ImNvbS5jb20ydXMuaGl2ZXNkay53aW5kb3dzLm1pY3Jvc29mdHN0b3JlLmdsb2JhbC5ub3JtYWwuaXRlbTAxIiwidmlkIjoiMjAwMDAwMTEzMzciLCJ1aWQiOiI2NzIwMDcxNyIsInZpZF90eXBlIjoidjQiLCJzZXJ2ZXJfaWQiOiJrciIsImFwcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2RrLndpbmRvd3MubWljcm9zb2Z0c3RvcmUuZ2xvYmFsLm5vcm1hbCIsImFtb3VudCI6IjEyMDAiLCJzdGFydGVkX2RhdGV0aW1lIjoiMjAyMy0wNy0yMSAyMDoxNzowNiIsInBhaWRfZGF0ZXRpbWUiOiIyMDIzLTA3LTIxIDIwOjE4OjEzIiwiY2FuY2VsbGVkX2RhdGV0aW1lIjoiMjAyMy0wNy0yMSAyMDoyMTo0NCIsImNhbmNlbGxlZF9yZWFzb24iOiJcdWQxNGNcdWMyYTRcdWQyYjggXHVhY2IwXHVjODFjIFx1Y2RlOFx1YzE4YyIsImN1cnJlbmN5IjoiS1JXIiwiYWRkaXRpb25hbEluZm8iOm51bGwsImhpdmVpYXBfcmVjZWlwdCI6InRKcHdRU0lsTkZpQ1NQb2tIU1JZVHZUTG10YkRpU1pua1lhNytJV2FNd009In0="
}