コンテンツにスキップ

Web PG 支払い

Web PG決済APIは、ウェブサイトでPG決済を実装したいときに使用されるAPIですが、Windowsアプリを開発する際にHive SDK billingを使用しません。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 製品タイプ(消耗品: consumable)

レスポンス要素

フィールド タイプ 必須 説明
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 > プロジェクト管理 > ゲーム会社ゲームを選択 > ゲーム詳細 > 基本情報**にある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 アプリ開発者が定義した購入メタ情報 こちら

リクエストの例

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

Bearerトークンは、Hiveコンソールの**App Center > プロジェクト管理 > ゲーム会社ゲームを選択 > ゲーム詳細 > 基本情報**にある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 支払い情報の暗号化ハッシュ
    ┕ 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)

Bearerトークンは、Hive コンソールの App Center > プロジェクト管理 > ゲーム会社ゲームを選択 > ゲーム詳細 > 基本情報 にある 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を確認できない; Derby Daysのゲストアカウントにはハブゲストアカウントがないため、ここに該当します
    ⠀⠀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などのエミュレーター経由でアクセスした場合は「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
    Content-Type text/html
    データ形式 JSON
    認証 Bearer (token)

Bearerトークンは、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 アイテム名
    ⠀⠀数量 数値 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

応答の例

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

支払い結果通知サービス

決済結果通知サービスは、決済が完了またはキャンセルされたときに、結果をゲームサーバーに即座に送信します。このAPIは、purchase_bypass_infoの値を、決済完了履歴照会と同様に送信し、ゲームがこの値を使用してレシートを確認し、ユーザーに製品を付与できるようにします。レシートの確認と製品の付与は、決済結果送信情報typeが支払い済みの場合にのみ行うべきです。

Note

このAPIを使用するには、まずHiveコンソールでPG会社を設定する必要があります。 レシートの確認と商品の配送には、この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 String M 購入ユーザーのプレイヤーID、v1認証用のVID
    vid_type String O SDKバージョンに応じたvidタイプ値 (デフォルトv4)
    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)
    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 支払い情報の暗号化されたハッシュ
    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を実装する必要があります。

「ユーザーの返金 ee-payment ターゲット 返金履歴照会」APIを使用する際は、以下にご注意ください。

  • PlayerID Lookup API のレスポンスアイテム内の is_refund フィールドは、true の場合にのみ使用できます。
  • 再払いケースの支払いをリクエストする際、リクエストパラメータ 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)

Bearerトークンは、Hiveコンソールの**App Center > プロジェクト管理 > ゲーム会社を選択 > ゲーム詳細 > 基本情報**にある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 ハイブマーケット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を再呼び出す必要があります。