Web PG 支払い

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

商品リストの取得¶

製品情報を取得中。アプリ内の製品リストを実装するために使用されます。

リクエストURL¶

Bearerトークンは、HiveコンソールのApp Center > プロジェクト管理 > ゲーム会社を選択 > ゲームの詳細 > 基本情報に見つかる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情報を使用して製品注文をリクエストします。

カスタム金額決済¶

カスタム金額決済は、製品PIDに設定された金額ではなく、ゲームサーバーが指定した金額（custom_price）で決済をリクエストできる機能です。

ゲーム内の製品にクーポン、ポイント、イベント割引などを適用したい場合、ゲームサーバーはすべての割引を適用した最終決済金額を計算し、その金額をcustom_price値としてAPIを呼び出す必要があります。custom_price値が提供されていない場合、製品PIDに設定された金額で決済が進行されます。

リクエストURL¶

ベアラートークンは、Hive コンソールの App Center > Project Management > Select Game Company > Game Details > Basic Information に見つかる Hive 認証キーに対応しています。

リクエストパラメータ¶

「PG決済完了ポップアップを閉じる」ボタンを機能させるには、PG決済呼び出しページに以下のスクリプトを追加する必要があります。

window.addEventListener('message', function(event) {
    const data = event.data;

    if (data?.type === 'REFRESH_PARENT') {
        if (typeof data.url === 'string' && data.url.trim() !== '') {
            window.location.href = data.url;
        } else {
            window.location.reload();
        }
    }
});

リクエストの例¶

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\"}", "expiration_time": 1745395211}' \
    -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 (token)

ベアラートークンは、Hive コンソールの App Center > Project Management > Select Game Company Game > Game Details > Basic Information に見つかる Hive 認証キーに対応しています。

リクエストパラメータ¶

名前	タイプ	必須 (必須: M, 任意: O)	説明
appid	文字列	M	Hive コンソールから登録され発行されたID > アプリセンター
market_id	数値	M	ユニークなマーケットID（固定値 `15` を使用）
server_id	文字列	M	支払いが発生したゲームサーバーを区別するためのコード
user_id_type	文字列	M	Hive ユーザータイプ（固定値 `player_id` を使用）
user_id	数値	M	Hive ユーザーID (`player_id`)

応答要素¶

名前	タイプ	必須 (必須: M, 任意: O)	説明
result	数値	M	レスポンスコード (0: 成功)
result_msg	文字列	M	レスポンスコードに応じた結果メッセージ
unconsumed_lists	オブジェクト配列	M
┕ market_pid	文字列	M	製品のユニークID
┕ order_id	文字列	M	注文番号
┕ server_id	文字列	M	購入ユーザーがアクセスしたゲームサーバーを区別するコード
┕ vid	文字列	M	購入ユーザーのプレイヤーID
┕ 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 TimeStamp ミリ秒)
┕ paid_datetime_ms	数値	M	支払いが完了した時刻 (Unix TimeStamp ミリ秒)
┕ hiveiap_receipt	文字列	M	支払い情報の暗号化ハッシュ
┕ purchase_bypass_info	文字列	M	領収書検証リクエストに必要な情報
┕ iap_payload	文字列	O	ゲームサーバーに送信するためにクライアントから受信した追加情報 (JSON文字列形式) (情報が受信されない場合はnullを返す)
┕ price_type	文字列	O	価格タイプ (none: 未使用, custom_price: カスタム金額決済)
┕ gameserver_price_verify_key	文字列	O	ゲームサーバー決済金額検証キー

リクエストの例¶

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,
            "price_type": "none",
            "gameserver_price_verify_key": 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
認証	Bearer (token)

ベアラートークンは、Hive コンソールの App Center > Project Management > Select Game Company > Game Details > Basic Information に見つかる Hive 認証キーに対応しています。

リクエストパラメータ¶

名前	タイプ	必須 (必須: M, 任意: O)	説明
purchase_bypass_info	文字列	M	レシートの代替および分析送信のためのデータ
game_info	オブジェクト配列	O	ゲームログや収益ログなど、ゲームに送信するログがある場合は、この値をゲームに追加して送信します。Hive IAPは、送信のために分析サーバーの代理として機能します。レシート検証ステージでは、アイテムが配信されたかどうか（itemsendok）を知ることはできないため、この部分は別途実装し、追加情報として提供する必要があります。
⠀⠀server_uid	bigint	O	ゲームサーバーによって発行されたユーザーID ない場合は、0
⠀⠀giftee_uid	bigint	O	null: 個人使用のための支払い 0: ギフトを受け取った人は存在しますが、UIDを確認できません
⠀⠀level	int	O	ユーザーのゲーム内レベル レベルがない場合は必要ありません。ない場合は、0。
⠀⠀character_id	bigint	O	サーバー内のユニークなキャラクター識別子の値 キャラクターの概念がない場合は、「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: 通常支払い)
hiveiap_iap_payload	文字列	O	クライアントからゲームサーバーに送信するために受け取った追加情報。JSON文字列形式であり、情報が受信されない場合は`null`を返します。
hiveiap_account_uuid_compare	数値	O	レシート検証APIに提供されたアカウント情報が、検証時にログインしているHiveアカウント情報と一致するかどうかを示します。同じマーケットアカウントを持つ複数のHiveアカウントが存在する可能性があります。(1: 一致, 2: 不一致, 9: サポートされていない)
hiveiap_price	文字列	O	決済金額。PGカスタム金額決済を使用する場合、悪用を防ぐために、検証キー(`gameserver_price_verify_key`)を使用してカスタム決済金額と実際の注文金額が同一であることをゲームサーバーで**必ず**確認する必要があります。
hiveiap_currency	文字列	O	決済通貨。PGカスタム金額決済を使用する場合、悪用を防ぐために、検証キー(`gameserver_price_verify_key`)を使用してカスタム決済金額の決済通貨と実際の注文決済金額の決済通貨が同一であることをゲームサーバーで**必ず**確認する必要があります。
gameserver_price_verify_key	文字列	O	ゲームサーバー決済金額検証キー。PGカスタム金額決済を使用する場合、悪用を防ぐために、このキーを使用してゲームサーバーで金額と通貨情報を比較検証する必要があります。

レスポンスコード¶

コード	メッセージ	コメント
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",
    "hiveiap_iap_payload": null,
    "hiveiap_account_uuid_compare": 9,
    "hiveiap_price": "1200",
    "hiveiap_currency": "KRW",
    "gameserver_price_verify_key": null
}

支払い結果処理¶

支払い結果処理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 > Project Management > Select Game Company Game > Game Details > Basic Information に見つかる 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 ユーザータイプ（固定値 `player_id` を使用）
user_id	数値	M	Hive ユーザーID（`player_id`）
asset	オブジェクト配列	O	付与されたアイテムに関する情報 付与が成功した場合のみ値を提供し、付与が失敗した場合は空の配列（[]）で応答する
asset_id	文字列	O	アイテムID
asset_name	文字列	O	アイテム名
⠀⠀quantity	数値	O	付与されたアイテムの数

レスポンス要素¶

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

リクエストの例¶

curl -L -v
 -d '{"hiveiap_transaction_id" : "HS_13","result_status": 1,"user_id_type": "player_id","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	String	M	購入ユーザーのPlayerID
vid_type	String	O	SDKバージョン (デフォルトv4)
uid	String	O	Hive メンバーシップUIDの購入ユーザー
amount	String	M	支払い金額
currency	String	M	支払い通貨
quantity	String	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)
started_datetime_ms	Number	M	支払いが開始された時間 (Unix TimeStamp ミリ秒)
paid_datetime_ms	Number	M	支払いが完了した時間 (Unix TimeStamp ミリ秒)
cancelled_datetime_ms	Number	O	支払いがキャンセルまたは返金された時間 (Unix TimeStamp ミリ秒)
cancelled_reason	String	O	支払いキャンセルまたは返金の理由
hiveiap_receipt	String	M	支払い情報の暗号化されたHASH
purchase_bypass_info	String	M	領収書確認リクエストに必要な情報
iap_payload	String	O	クライアントから受信した追加情報をゲームサーバーに送信するためのものです。JSON文字列形式で、情報が受信されない場合はnullを返します。
price_type	String	O	価格タイプ（none: 未使用、custom_price: カスタム金額決済）
gameserver_price_verify_key	String	O	ゲームサーバー決済金額検証キー

支払い結果送信の例（支払い完了時）¶

{
    "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...",
    "price_type": "none",
    "gameserver_price_verify_key": null
}

支払い結果送信の例（支払いキャンセルの場合）¶

{
    "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...",
    "price_type": "none",
    "gameserver_price_verify_key": null
}

ユーザー返金再支払い対象返金履歴照会API¶

このAPIは、返金を要求したユーザーの返金履歴を取得し、再支払いを行う必要があるユーザーのためのものです。
返金ユーザーの再支払い機能を自己実装したウェブストアで有効にしている場合は、「返金ユーザー再支払い対象返金履歴照会」APIからの応答値を使用して、返金ユーザーのための再支払い通知ポップアップUIを実装する必要があります。

「ユーザー返金再支払い対象返金履歴照会」APIを使用する際は、以下の事項にご注意ください。

• PlayerID Lookup API からの is_refund レスポンス項目は、それが true の場合にのみ使用できます。
• 再払いケースの支払いをリクエストする際、リクエストパラメータ json には refund_idx(Integer) と is_repayment(Integer) を必須項目として含める必要があります。
• カスタム金額決済ケースを再支払いする場合、支払いリクエストを行う際にcustom_priceとgameserver_price_verify_keyフィールドに値を設定する必要があります。この場合、gameserver_price_verify_keyフィールドをrefundに設定します。
• 再払いリクエストを行う際、server_idフィールドをrefundに設定します。

リクエストURL¶

ベアラートークンは、Hive コンソールの App Center > Project Management > Select Game Company > Game Details > Basic Information に見つかる Hive 認証キーに対応しています。

リクエストパラメータ¶

応答要素¶

リクエストの例¶

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

応答の例¶

{
  "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,
      "price": "1200",
      "currency": "KRW",
      "display_price": "₩1,200"
    }
  ]
}

ユーザー返金再支払い通知ポップアップの例¶