PG 支払い
次は、Windows OSゲームでPG決済をサポートするためにゲームサーバーで実装すべきPG決済APIです。Windows環境でのPG決済に関する詳細はこちらをご確認ください。
支払い完了履歴の確認¶
決済完了時に決済代行会社（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 |
| コンテンツタイプ | application/json |
| データ形式 | JSON |
| 認証 | Bearer (トークン) |
BearerトークンはHiveコンソール アプリセンター > プロジェクト管理 > ゲーム会社ゲーム選択 > ゲーム詳細 > 基本情報 におけるHive認証キーに該当します。
リクエストパラメータ¶
| 名称 | タイプ | 必須要件 (必須: M, オプション: O) | 説明 |
|---|---|---|---|
| appid | 文字列 | M | Hiveコンソール > アプリセンターで登録および発行されたID |
| market_id | 数値 | M | マーケット固有ID (15固定) |
| server_id | 文字列 | M | 決済が発生したゲームサーバー区分コード |
| user_id_type | 文字列 | M | HIVEユーザータイプ uid : 個別モジュール(v0) vid : 認証v1(v1) player_id : 認証v4(v4) |
| user_id | 数値 | M | HIVEユーザーID user_id_typeに応じて送信 uid : 個別モジュール(v0) vid : 認証v1(v1) player_id : 認証v4(v4) |
応答要素¶
| 名称 | タイプ | 必須要件 (必須: M, オプション: O) | 説明 |
|---|---|---|---|
| result | 数値 | M | 応答コード (0: 成功) |
| result_msg | 文字列 | M | 応答コードに応じた結果メッセージ |
| unconsumed_lists | オブジェクト配列 | M | |
| ┕ market_pid | 文字列 | M | 商品固有ID |
| ┕ order_id | 文字列 | M | 注文番号 |
| ┕ server_id | 文字列 | M | 購入したユーザーが接続したゲームサーバー区分コード |
| ┕ vid | 文字列 | M | 購入したユーザーのPlayerID, v1認証の場合はVID |
| ┕ uid | 文字列 | O | 購入したユーザーのuid |
| ┕ amount | 文字列 | M | 支払い金額 |
| ┕ currency | 文字列 | M | 支払い通貨 |
| ┕ quantity | 数値 | M | 購入数量 |
| ┕ started_datetime | 日時 | M | 支払いを開始した時間 (Y-m-d H:i:s) |
| ┕ paid_datetime | 日時 | M | 支払いを完了した時間 (Y-m-d H:i:s) |
| ┕ hiveiap_receipt | 文字列 | M | 支払い情報の暗号化HASH |
| ┕ purchase_bypass_info | 文字列 | M | 領収書検証要求に必要な必須情報 |
| ┕ additionalInfo | 文字列 | 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 |
| AUTHORIZATION | 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 | 数値 | M | 応答コード (Response Code を参照) |
| result_msg | 文字列 | M | 応答コードに応じた結果メッセージ |
| hiveiap_transaction_id | 文字列 | M | 検証成功した領収書ごとに生成されるトランザクションID。この値をゲームサーバーに保存してゲームが領収書の重複チェックを実施する |
| hiveiap_market_id | 文字列 | O | マーケットの固有番号 (PG決済: 15 固定) |
| hiveiap_market_pid | 文字列 | O | 決済商品PID |
| hiveiap_market_transaction_id | 文字列 | O | 注文に対する固有の注文番号 |
| hiveiap_receipt | 文字列 | O | マーケット領収書のObject値 (PG決済: null 固定) |
| hiveiap_purchase_test | 文字列 | 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 | 数字 | M | 応答コード (0: 成功) |
| result_msg | 文字列 | 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
応答の例¶
支払い結果通知サービス¶
決済結果通知サービスは、決済完了または決済キャンセルが発生する即時に、その結果をゲームサーバーに送信します。このAPIは決済完了履歴照会と同様にpurchase_bypass_info値を渡すため、ゲームはこの値を使用して領収書を検証した後、ユーザーに商品を提供することができます。決済結果送信情報でtypeがpaidの場合のみ、領収書の検証と商品提供を行う必要があります。
Note
このAPIを使用するには、まず[Hiveコンソールで使用するPG会社を設定](../../../operation/billing/pg_mangement/#ftoc-heading-6)する必要があります。
領収書の検証と商品の支給のためには、このAPIまたは決済完了履歴照会APIのいずれか一方のみを使用することをお勧めします。
決済結果送信の基本事項¶
| 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..."
}