Web PG 支払い
Web PG決済APIは、ウェブサイトでPG決済を実装したいときに使用されるAPIですが、Windowsアプリを開発する際にはHive SDK請求を使用しません。Web PG決済APIは、アプリ内でPG決済を実装するAPIとは異なります。
Note
アプリにPG決済を実装するには、Hive SDK Billingと一般PG決済APIを使用する必要があります。
商品リストの取得¶
製品情報を取得中。アプリの製品リストを実装するために使用されます。
リクエストURL¶
環境 | URL |
---|---|
本番URL | https://store.withhive.com/external/api/product |
サンドボックスURL | https://sandbox-store.withhive.com/external/api/product |
HTTPメソッド | POST |
Content-Type | text/html; charset=utf-8 |
データ形式 | JSON |
認証 | Bearer (token) |
Bearerトークンは、HiveコンソールのApp Center > プロジェクト管理 > ゲーム会社を選択 > ゲーム詳細 > 基本情報に見つかるHive認証キーに対応しています。
リクエストパラメータ¶
フィールド | タイプ | 必須 | 説明 |
---|---|---|---|
api | 文字列 | O | API識別子の値(固定値`product`を使用) |
market_id | 文字列 | O | Hive マーケットID(PG決済: 固定値`15`を使用) |
appid | 文字列 | O | Hive アプリID |
hive_country | 文字列 | O | 国コード(ISO 3166-1 2文字) |
game_language | 文字列 | O | 言語(ISO 639-1 2文字) |
vid | 文字列 | O | Hive アカウント情報(プレイヤーID) |
vid_type | 文字列 | O | アカウントタイプ(v4) |
market_pid_type | 文字列 | O | 製品タイプ(消耗品) |
応答要素¶
フィールド | タイプ | 必須 | 説明 |
---|---|---|---|
result | 整数 | O | レスポンスコード(0は成功、その他はエラー) |
result_msg | 文字列 | O | レスポンスメッセージ |
product_list | オブジェクト | O | 製品情報のリスト |
product_list > market_pid | 文字列 | O | 製品PID |
product_list > price | 整数 | O | 製品価格(数値) |
product_list > currency | 文字列 | O | 製品価格の通貨 |
product_list > display_price | 文字列 | O | 製品価格(通貨記号を含む) |
product_list > title | 文字列 | O | 製品名 |
product_list > description | 文字列 | O | 製品説明 |
product_list > product_type | 文字列 | O | 製品分類(消耗品) |
update_date | 文字列 | O | 製品PID情報の最終更新日時 |
リクエストの例¶
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¶
環境 | URL |
---|---|
本番URL | https://store.withhive.com/external/api/order |
サンドボックスURL | https://sandbox-store.withhive.com/external/api/order |
HTTPメソッド | POST |
Content-Type | text/html; charset=utf-8 |
データ形式 | JSON |
認証 | Bearer (token) |
Bearerトークンは、HiveコンソールのApp Center > Project Management > Select Game Company > Game Details > Basic InformationにあるHive認証キーに対応しています。
リクエストパラメータ¶
フィールド | タイプ | 必須 | 説明 |
---|---|---|---|
market_id | 文字列 | O | Hive マーケット ID |
appid | 文字列 | O | Hive Appid |
hive_country | 文字列 | O | 国コード (ISO 3166-1 2文字) |
game_language | 文字列 | O | 言語 (ISO 639-1 2文字) |
vid | 文字列 | O | Hive アカウント情報 (プレイヤー ID) |
vid_type | 文字列 | O | アカウントタイプ (v4) |
market_pid | 文字列 | O | 製品 PID |
server_id | 文字列 | O | サーバー ID |
os | 文字列 | O | Windows: W, MAC: M, Android: A |
quantity | 整数 | X | 購入数量 (送信されない場合のデフォルト値は 1) |
iap_payload | 文字列 | X | アプリ開発者によって定義された購入メタデータ 購入メタ情報 |
fixed_currency | 文字列 | X | 支払い方法の露出に使用する通貨 (ISO 4217 3文字) * fixed_currency パラメータが存在しない場合は必須ではありません。fixed_currency パラメータが追加されると、支払い方法は fixed_currency 通貨に基づいて露出されます。 |
refund_idx | 整数 | X | 返金ユーザー再支払いリスト IDX * 返金ユーザー再支払いリクエストのみに必要 |
is_repayment | 整数 | X | 返金ユーザー再支払いかどうか (0: 通常の支払い, 1: 返金ユーザー再支払い) * 返金ユーザー再支払いリクエストのみに必要 |
expiration_time | 整数 | X | これは支払いウィンドウの有効期限です。Unix タイムスタンプミリ秒形式 (例: 1745395211) です。Hive 課金サーバーの現在の時間 (Unix タイムスタンプミリ秒) がこの値を超えると、レスポンス内の支払いウィンドウ HTML ページの代わりに異なるガイダンスページが返されます。 |
リクエストの例¶
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 (トークン) |
---|
ベアラートークンは、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 | 購入ユーザーのPlayerID |
┕ 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を返す) |
リクエストの例¶
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 |
認証 | Bearer (token) |
---|
ベアラートークンは、Hive コンソールの App Center > Project Management > Select Game Company > Game Details > Basic Information に見つかる Hive 認証キーに対応しています。
リクエストパラメータ¶
名前 | タイプ | 必須 (必須: M, 任意: O) | 説明 |
purchase_bypass_info | String | M | レシート代替および分析送信のためのデータ |
game_info | Object Array | 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`を返します。 |
応答コード¶
コード | メッセージ | コメント |
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
}
支払い結果処理¶
支払い結果処理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 コンソールのアプリセンター > プロジェクト管理 > ゲーム会社を選択 > ゲーム詳細 > 基本情報にある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 | アイテム名 |
⠀⠀数量 | 数値 | 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
応答の例¶
支払い結果通知サービス¶
支払い結果通知サービスは、支払いの完了またはキャンセル時にすぐにゲームサーバーに結果を送信します。この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 |
vid_type | 文字列 | O | SDKバージョン (デフォルトv4) |
uid | 文字列 | O | Hive メンバーシップ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 TimeStamp ミリ秒) |
paid_datetime_ms | 数値 | M | 支払いが完了した時間 (Unix TimeStamp ミリ秒) |
cancelled_datetime_ms | 数値 | O | 支払いがキャンセルまたは返金された時間 (Unix TimeStamp ミリ秒) |
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..."
}
ユーザーの返金再支払い対象返金履歴照会API¶
このAPIは、返金を要求したユーザーの返金履歴を取得し、再支払いを行う必要があるユーザーのためのものです。
あなたの自己実装したウェブストアで返金ユーザーの再支払い機能を有効にしている場合は、「返金ユーザー再支払い対象返金履歴照会」APIからの応答値を使用して、返金ユーザーのための再支払い通知ポップアップUIを実装する必要があります。
「ユーザー返金再支払い対象返金履歴照会」APIを使用する際は、以下の事項にご注意ください。
- PlayerID Lookup API からの
is_refund
レスポンス項目は、真である場合にのみ使用できます。 - 再払いケースの支払いをリクエストする際、リクエストパラメータ json には
refund_idx(Integer)
とis_repayment(Integer)
を必須項目として含める必要があります。
リクエストURL¶
環境 | URL |
---|---|
本番URL | https://store.withhive.com/external/api/refund_info |
サンドボックスURL | https://sandbox-store.withhive.com/external/api/refund_info |
HTTPメソッド | POST |
Content-Type | text/html; charset=utf-8 |
データ形式 | JSON |
認証 | Bearer (token) |
ベアラートークンは、Hive コンソールのアプリセンター > プロジェクト管理 > ゲーム会社を選択 > ゲーム詳細 > 基本情報に見つかるHive 認証キーに対応しています。
リクエストパラメータ¶
フィールド | タイプ | 必須 | 説明 |
---|---|---|---|
appid | 文字列 | O | Hive Appid |
vid_type | 文字列 | O | アカウントタイプ ("v4") |
vid | 文字列 | O | Hive アカウント情報 (プレイヤーID) |
game_language | 文字列 | O | 言語 (ISO 639-1 2文字) |
device | 文字列 | X | PC、モバイルの区別 (pc, mobile) * デバイス項目が存在しない場合、レスポンスではモバイルに設定されます |
レスポンス要素¶
フィールド | タイプ | 必須 | 説明 |
---|---|---|---|
result | 整数 | O | レスポンスコード(0は成功、それ以外はエラー) |
result_msg | 文字列 | O | レスポンスメッセージ |
guide_title | 文字列 | O | ガイドタイトル |
guide_content | 文字列 | O | ガイドコンテンツ |
customer_site | オブジェクト | O | カスタマーサービスの住所 |
customer_site > pc | 文字列 | O | PCカスタマーサービスの住所 |
customer_site > mobile | 文字列 | O | モバイルカスタマーサービスの住所 |
refund_list | 配列 > オブジェクト | O | 返金再支払いリスト |
refund_list > refund_idx | 整数 | X | 再支払いINDEX ID |
refund_list > market_id | 整数 | X | Hive マーケットID |
refund_list > market_pid | 文字列 | X | 製品PID |
refund_list > refund_time | 文字列 | X | 返金日時 |
refund_list > refund_time_ms | 整数 | X | 返金日時(Unixタイムスタンプミリ秒) |
refund_list > quantity | 整数 | X | 製品購入数量 |
リクエストの例¶
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
}
]
}
ユーザー返金再支払い通知ポップアップの例¶
Warning
ユーザーは、再購入の支払いを完了した後に再購入アイテムのリストを更新できる「リフレッシュ」ボタンを実装する必要があります。 再購入の支払いを完了した後、「ユーザー再購入対象返金履歴照会」APIを再呼び出して認証解除フローを進める必要があります。