コンテンツにスキップ

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 (token)

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)
┕ started_datetime_ms 数値 M 支払い開始時間 (Unix タイムスタンプ ミリ秒)
┕ paid_datetime_ms 数値 M 支払い完了時間 (Unix タイムスタンプ ミリ秒)
┕ hiveiap_receipt 文字列 M 支払い情報の暗号化されたHASH
┕ purchase_bypass_info 文字列 M レシート検証リクエストに必要な情報
┕ iap_payload 文字列 O クライアントから受信したゲームサーバーに送信する追加情報 (JSON文字列形式)
(情報が受信されない場合は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...",
            "started_datetime_ms": 1647925429000,
            "paid_datetime_ms": 1647925479000,
            "iap_payload": null
        }
    ]
}

支払い情報の確認

支払い結果検証APIは、IAP v4 レシート検証に基づいています。

支払い結果の検証は、以前に受け取ったpurchase_bypass_infoを使用します。purchase_bypass_infoには、支払いを進める前にSDKを通じて受け取ったさまざまな情報が含まれており、Hive Analyticsに送信されます。領収書検証リクエストと一緒に販売ログを送信する必要がある場合は、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 (token)

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

リクエストパラメータ

名前 タイプ 必須 (必須: M, 任意: O) 説明
purchase_bypass_info 文字列 M レシートの代替と分析送信のためのデータ
game_info オブジェクト配列 O ゲームログや収益ログなど、ゲームに送信するログがある場合、この値を追加してゲームに送信する必要があります。これにより、Hive IAPが分析サーバーに送信する仲介者として機能します。レシート検証段階では、アイテムが送信されたかどうかを知ることはできないため（itemsendok）、この部分は別途実装し、追加情報として提供する必要があります。
⠀⠀server_uid bigint O ゲームサーバーによって発行されたuser_id
ない場合は、0
⠀⠀giftee_uid bigint O null: 個人使用の支払い
0: ギフトの受取人がいるが、UIDを確認できない; Derby DaysのゲストアカウントにはHubゲストアカウントがないため、ここに該当します
⠀⠀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 BlueStacksのようなPCエミュレーター経由でアクセスする場合は「1」を入力し、それ以外の場合は「0」を入力

応答要素

名前 タイプ 必須 (必須: M, オプション: O) 説明
result 数字 M レスポンスコード (レスポンスコードを参照)
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 マーケットレシートオブジェクトの値 (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 (token)

ベアラートークンは、Hive コンソール App Center > プロジェクト管理 > ゲーム会社を選択 > ゲーム詳細 > 基本情報 に見つかる Hive 認証キーに対応しています。

リクエストパラメータ

名前 タイプ 必須
(必須: M, オプション: O)		 説明
hiveiap_transaction_id 文字列 M 受領確認結果のhiveiap_transaction_id
result_status 数値 M アイテム配信成功ステータス
0: 配信失敗
1: 配信成功
2: 支払いキャンセル返金リクエスト (PGのみ)
result_status_message 文字列 O 配信失敗または支払いキャンセルリクエストの理由
user_id_type 文字列 M Hive ユーザータイプ
v0: 個人モジュール (uid)
v1: 認証 v1 (vid)
v4: 認証 v4 (player_id)
user_id 数値 M ユーザーID
user_id_typeがv0の場合はuidを送信; v1の場合はvidを送信; v4の場合はplayer_idを送信
asset オブジェクト配列 O 配信されたアイテムに関する情報
配信が成功した場合のみ値を提供し、配信が失敗した場合は空の配列 ([]) で応答
⠀⠀asset_id 文字列 O アイテムID
⠀⠀asset_name 文字列 O アイテム名
⠀⠀quantity 数値 O 配信されたアイテムの数

応答要素

名前 タイプ 必須
(必須: M, 任意: O)		 説明
result 数字 M レスポンスコード (0: 成功)
result_msg 文字列 M レスポンスコードに応じた結果メッセージ

リクエストの例

  • Call
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は、購入結果取得 APIと同様にpurchase_bypass_info値を渡し、ゲームがこの値を使用して領収書を検証し、その後ユーザーに製品を付与できるようにします。領収書の検証と製品の付与は、支払い結果伝送情報のtypeが支払い済みの場合にのみ進めるべきです。

Note

このAPIを使用するには、まずHiveコンソールでPG会社を設定する必要があります。 受領確認と商品配送のためには、このAPIまたは支払い完了履歴照会APIのいずれかを使用することをお勧めします。

支払い結果送信に関する基本情報

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

支払い結果送信情報

名前 タイプ 必須
(必須: M, オプション: O)		 説明
type 文字列 M 通知タイプ（paid: 支払い完了、cancelled: 支払いキャンセルまたは返金）
market_pid 文字列 M ユニークな商品ID
order_id 文字列 M 注文番号
server_id 文字列 M 購入ユーザーがアクセスしたゲームサーバーを区別するコード
vid 文字列 M 購入ユーザーのPlayerID、v1認証用のVID
vid_type 文字列 O SDKバージョンに応じたvidタイプの値（デフォルトはv4）
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）
cancelled_datetime 日時 O 支払いがキャンセルまたは返金された時間（Y-m-d H:i:s）
started_datetime_ms 数値 M 支払いが開始された時間（Unixタイムスタンプミリ秒）
paid_datetime_ms 数値 M 支払いが完了した時間（Unixタイムスタンプミリ秒）
cancelled_datetime_ms 数値 O 支払いがキャンセルまたは返金された時間（Unixタイムスタンプミリ秒）
cancelled_reason 文字列 O 支払いのキャンセルまたは返金の理由
hiveiap_receipt 文字列 M 支払い情報の暗号化されたHASH
purchase_bypass_info 文字列 M レシート検証リクエストに必要な情報
iap_payload 文字列 O クライアントから受け取った追加情報で、ゲームサーバーに送信される。JSON文字列形式で、情報が受信されない場合は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,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "started_datetime_ms": 1689938226000,
    "paid_datetime_ms": 1689938293000,
    "cancelled_datetime_ms": null,
    "iap_payload": null,
    "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,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "started_datetime_ms": 1689938226000,
    "paid_datetime_ms": 1689938293000,
    "cancelled_datetime_ms": 1689938504000,
    "iap_payload": null,
    "purchase_bypass_info": "eyJ0eXBlIjoiY2FuY2VsbGVkIiwibWFya2V0X2lkIjoiMT..."
}