Web PG 支払い

ウェブPG決済APIは、Windowsアプリ開発時にHive SDKビリングを使用しませんが、ウェブサイトでPG決済を実装したいときに使用するAPIです。ウェブPG決済APIは、アプリでPG決済を実装するAPIとは異なります。

商品リストの取得¶

商品情報を取得します。アプリで商品リストを実装するために使用します。

リクエストURL¶

BearerトークンはHiveコンソールアプリセンター > プロジェクト管理 > ゲーム会社ゲーム選択 > ゲーム詳細 > 基本情報でHive認証キーに相当します。

リクエストパラメータ¶

レスポンス要素¶

リクエストの例¶

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

応答の例¶

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

商品注文リクエスト¶

商品リストから選択したPID（商品ID）情報で商品注文をリクエストします。

リクエストURL¶

BearerトークンはHiveコンソールアプリセンター > プロジェクト管理 > ゲーム会社ゲーム選択 > ゲーム詳細 > 基本情報でHive認証キーに相当します。

リクエストパラメータ¶

リクエストの例¶

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

レスポンス例¶

商品注文リクエストが正常に処理されると、決済手段を選択するポップアップウィンドウを返します。以下のポップアップウィンドウを構成するHTMLページを返します。

支払い完了履歴の照会¶

決済完了時に決済代行会社（PG）はHive IAP v4サーバーに決済結果を直接伝達します。この方式はネットワークの不安定性を補完し、決済データの改ざんを防ぎます。 事前作業では、登録した決済情報と決済代行会社（PG）の情報を照合してクロス検証を行います。決済情報の完全性が確認されると、追加の安全装置を確保し、決済情報を保存します。保存された決済情報は決済完了履歴照会APIを通じて照会できます。

クライアントでは、利用者の決済完了情報が必要な時点にゲームサーバーに情報をリクエストし、ゲームサーバーはHive IAP v4サーバーを通じて決済情報を照会します。利用者の決済履歴が存在する場合はpurchase_bypass_infoを活用して決済情報の検証を行います。

リクエストURL¶

商用URL	https://hiveiap.qpyou.cn/api_v4/purchases/unconsumed
サンドボックスURL	https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed
HTTPメソッド	POST
Content-Type	application/json
データフォーマット	JSON
認証	Bearer (トークン)

BearerトークンはHiveコンソールアプリセンター > プロジェクト管理 > ゲーム会社ゲーム選択 > ゲーム詳細 > 基本情報でHive認証キーに相当します。

リクエストパラメータ¶

名称	タイプ	必須かどうか (必須: M, オプション: O)	説明
appid	String	M	Hiveコンソール > アプリセンターで登録および発行されたID
market_id	Number	M	マーケット固有ID (`15` 固定値使用)
server_id	String	M	決済が発生したゲームサーバー区分コード
user_id_type	String	M	HIVEユーザータイプ uid : 個別モジュール(v0) vid : 認証v1(v1) player_id : 認証v4(v4)
user_id	Number	M	HIVEユーザーID user_id_typeに応じて送信 uid : 個別モジュール(v0) vid : 認証v1(v1) player_id : 認証v4(v4)

レスポンス要素¶

名称	タイプ	必須かどうか (必須: M, オプション: O)	説明
result	Number	M	応答コード (0: 成功)
result_msg	String	M	応答コードに基づく結果メッセージ
unconsumed_lists	Object Array	M
┕ market_pid	String	M	商品固有ID
┕ order_id	String	M	注文番号
┕ server_id	String	M	購入したユーザーが接続したゲームサーバーの区分コード
┕ vid	String	M	購入したユーザーのPlayerID、v1認証の場合はVID
┕ uid	String	O	購入したユーザーのuid
┕ amount	String	M	決済金額
┕ currency	String	M	決済通貨
┕ quantity	Number	M	購入数量
┕ started_datetime	Datetime	M	決済を開始した時間 (Y-m-d H:i:s)
┕ paid_datetime	Datetime	M	決済を完了した時間 (Y-m-d H:i:s)
┕ hiveiap_receipt	String	M	決済情報暗号化HASH
┕ purchase_bypass_info	String	M	領収書検証リクエストに必要な必須情報
┕ additionalInfo	String	O	ゲームサーバーに送信するためにクライアントから受け取った追加情報 (JSON String形式) (受け取った情報がない場合はnullを返す)

リクエストの例¶

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

応答例¶

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

支払い情報の検証¶

決済結果検証APIは IAP v4 レシート検証 を基にしています。

決済結果の検証は、前に受け取ったpurchase_bypass_infoを利用します。purchase_bypass_infoは、決済を進める前にSDKを通じて受け取った各種情報を含んでおり、Hiveアナリティクスに送信されます。 領収書検証リクエストとともに売上ログの送信が必要な場合は、game_infoを利用してください。受け取ったgame_infoは、Hive IAPでアナリティクスサーバーへのログ送信を代行します。

リクエストURL¶

商用URL	https://hiveiap-verify.qpyou.cn/api_v4/verify
サンドボックスURL	https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify
HTTPメソッド	POST
コンテンツタイプ	text/html
データ形式	JSON
認証	Bearer (トークン)

BearerトークンはHiveコンソールアプリセンター > プロジェクト管理 > ゲーム会社ゲーム選択 > ゲーム詳細 > 基本情報でHive認証キーに相当します。

リクエストパラメータ¶

名称	タイプ	必須かどうか (必須: M, オプション: O)	説明
purchase_bypass_info	String	M	領収書の代用および分析送信用データ
game_info	Object Array	O	ゲームログ、売上ログなど、ゲームに送信するログがある場合、この値をゲームに追加して送信すると、Hive IAPが分析サーバーへの送信を代行します。領収書検証段階ではアイテム送信完了(itemsendok)の有無はわからないため、この部分は別途実装して追加情報として提供する必要があります。
⠀⠀server_uid	bigint	O	ゲームサーバーで発行されるuser_id ない場合は0
⠀⠀giftee_uid	bigint	O	null: 自分自身のための決済 0: プレゼントを受け取った人がいるがUID確認不可、ダービーデイズゲストアカウントはハブゲストアカウントがないため、ここに該当
⠀⠀level	int	O	ユーザーのゲーム内レベル レベルがない場合は不要。ない場合は0。
⠀⠀character_id	bigint	O	サーバー内でユニークなキャラクター区別値 (PK?). キャラクター概念がない場合は「0」
⠀⠀character_type_id	int	O	キャラクタータイプ区別値 キャラクター概念がないゲームは「0」を入力
⠀⠀character_level	int	O	キャラクタータイプ区別値 キャラクター概念がないゲームは「0」を入力
⠀⠀is_emulator	int	O	ブルースタックなどPC用エミュレーターで接続する場合は「1」、それ以外は「0」を入力

応答要素¶

名称	タイプ	必須かどうか (必須: M, オプション: O)	説明
result	Number	M	応答コード (Response Code を参照)
result_msg	String	M	応答コードに基づく結果メッセージ
hiveiap_transaction_id	String	M	検証成功した領収書ごとに生成されるトランザクションID。この値をゲームサーバーに保存して、ゲームが領収書の重複チェックを行います。
hiveiap_market_id	String	O	マーケット固有番号 (PG決済: 15固定)
hiveiap_market_pid	String	O	決済商品PID
hiveiap_market_transaction_id	String	O	注文に対する固有注文番号
hiveiap_receipt	String	O	マーケット領収書Object値 (PG決済: null固定)
hiveiap_purchase_test	String	O	テスト決済かどうか (Y: テスト決済 / N: 通常決済)

レスポンスコード¶

コード	メッセージ	コメント
0	成功、重複した領収書	検証成功
1000001	要求されたパラメータがありません	送信されたパラメータがないとき
1000003	DB接続エラー	DB接続ができないとき
1000005	内部サーバーエラー	内部サーバーエラー
1000006	必要なパラメータ情報が欠落しています	必須パラメータ値がないとき
1000503	領収書の認証に失敗しました	領収書の検証に失敗またはハッキングされた領収書の場合 (例: スプーフィングハッキング)
1000507	購入情報の保存に失敗しました	購入履歴保存失敗
1000524	領収書の認証に失敗しました。(存在しない注文)	領収書検証失敗 (存在しない注文)
1000525	領収書の認証に失敗しました。(不正なパラメータ)	領収書検証失敗 (パラメータエラー)

リクエストの例¶

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

応答の例¶

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

支給結果処理¶

支給結果処理 APIは IAP v4 アイテム支給結果送信を基にしています。支給結果処理 APIを通じてアイテム購入から支給完了までの決済処理を最終的に完了させます。決済処理が完了していない場合、ユーザーは同じ商品を購入することができません。購入を試みて決済ページに入ると、「既に保有している商品です。」というメッセージが表示され、決済は進行しません。

複数の決済ウィンドウを開いて購入・決済を試みた場合でも、決済処理が行われていない商品はすべて自動的にキャンセル処理されます。ゲームサーバーで行う購入回数制限の確認、アイテムの支給など、すべての決済プロセスを処理した後、決済結果を送信して決済が完了したことをHive IAP v4サーバーに通知します。決済キャンセルをリクエストしたい場合も、支給結果処理APIを通じてキャンセルをリクエストできます。

リクエストURL¶

商用URL	https://hiveiap.qpyou.cn/api_v4/item_result
サンドボックスURL	https://sandbox-hiveiap.qpyou.cn/api_v4/item_result
HTTPメソッド	POST
コンテンツタイプ	text/html
データフォーマット	JSON
認証	Bearer (トークン)

BearerトークンはHiveコンソールアプリセンター > プロジェクト管理 > ゲーム会社ゲーム選択 > ゲーム詳細 > 基本情報でHive認証キーに相当します。

リクエストパラメータ¶

名称	タイプ	必須かどうか (必須: M, オプション: O)	説明
hiveiap_transaction_id	String	M	領収書検証結果の hiveiap_transaction_id
result_status	Number	M	アイテム付与成功の有無 0: 付与失敗 1: 付与成功 2: 決済キャンセル返金リクエスト (PG専用)
result_status_message	String	O	付与失敗または決済キャンセルリクエストの理由
user_id_type	String	M	Hiveユーザータイプ v0: 個別モジュール (uid) v1: 認証 v1 (vid) v4: 認証 v4 (player_id)
user_id	Number	M	ユーザーID user_id_typeが v0の場合は uidを、v1の場合は vidを、v4の場合は player_idを送信
asset	Object Array	O	付与したアイテム情報 付与成功時のみ値を渡し、付与失敗時は空の配列([])で応答
asset_id	String	O	アイテムID
asset_name	String	O	アイテム名
⠀⠀quantity	Number	O	付与したアイテムの個数

応答要素¶

名称	タイプ	必須かどうか (必須: M, オプション: O)	説明
result	Number	M	応答コード (0: 成功)
result_msg	String	M	応答コードに基づく結果メッセージ

リクエストの例¶

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

レスポンス例¶

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

決済結果通知サービス¶

決済結果通知サービスは、決済完了または決済キャンセルが発生する即座に、その結果をゲームサーバーに送信します。このAPIは 決済完了履歴照会 と同様に purchase_bypass_info 値を渡すため、ゲームはこの値を使用して領収書を検証した後、ユーザーに商品を提供できます。 決済結果送信情報 で type が paid の場合にのみ、領収書の検証と商品提供を行う必要があります。

決済結果送信基本事項¶

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

支払い結果送信情報¶

名称	タイプ	必須かどうか (必須: M, オプション: O)	説明
type	String	M	通知タイプ(paid: 支払い完了, cancelled: 支払いキャンセルまたは返金)
market_pid	String	M	商品固有ID
order_id	String	M	注文番号
server_id	String	M	購入したユーザーが接続したゲームサーバーの区分コード
vid	Number	M	購入したユーザーのPlayerID, v1認証の場合はVID
vid_type	String	O	SDKバージョンに応じたvidタイプ値(デフォルトv4)
uid	Number	O	購入したユーザーのuid
amount	String	M	支払い金額
currency	String	M	支払い通貨
quantity	Number	M	購入数量
started_datetime	Datetime	M	支払いを開始した時間 (Y-m-d H:i:s)
paid_datetime	Datetime	M	支払いを完了した時間 (Y-m-d H:i:s)
cancelled_datetime	Datetime	O	支払いがキャンセルまたは返金された時間 (Y-m-d H:i:s)
cancelled_reason	String	O	支払いがキャンセルまたは返金された理由
hiveiap_receipt	String	M	支払い情報暗号化HASH
purchase_bypass_info	String	M	領収書検証リクエストに必要な必須情報
additionalInfo	String	O	ゲームサーバーに送信するためにクライアントから受け取った追加情報です。JSON String形式で、受け取った情報がない場合はnullを返します。

決済結果送信例 (決済完了時)¶

{
    "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": "eyJ0eXBlIjoicGFpZCIsIm1hcmtldF9pZCI6IjE1Iiwib3JkZXJfaWQiOi..."
}

決済結果送信例 (決済キャンセル時)¶

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