決済金額検証 API

「決済金額検証」APIは、ユーザーがウェブショップの商品割引やクーポンを適用して変更された金額の商品を購入しようとする際に、ゲームサーバーから発行された検証キーを使用して割引された決済金額を検証することをサポートします。有効な検証キーで決済が行われると、最終的にゲームサーバーから商品を支給できます。

動作フロー¶

「決済金額検証」API呼び出しから最終商品支給までの全体的な処理順序およびシステム間の処理過程を説明します。

Hive サーバーとアプリサーバー間の動作およびデータフローは以下の通りです。

ユーザーアクション：Hive ウェブショップで割引またはクーポンが適用されて割引された金額の商品を購入する際、「決済金額検証」APIが呼び出されます。
Hive サーバー：Hive コンソール決済金額検証に登録されたAPI（アプリサーバー）に検証キーを要求します。この時、商品ID、価格情報、クーポンコードなどをコールバック形式で配信します。
- Hive コンソール決済金額検証 API 登録：前提条件を参照
アプリサーバー：受け取った商品IDおよび価格情報などを検証した後、決済検証に使用される検証キー（gameserver_price_verify_key）をレスポンスとして返します。
Hive サーバー：アプリサーバーから受け取った検証キーと共に商品IDおよび価格情報などを課金サーバーに転送して決済を要求します。
アプリサーバー：課金サーバーの決済完了結果として渡された検証キー、商品ID、価格情報などを確認します。受け取った検証キーが手順3で検証、発行した値と一致する場合のみ決済を有効と判断します。検証に成功した場合のみ商品を支給します。
- アカウント別購入制限・購入数量制限設定商品：ウェブショップ購入制限検証を参照

前提条件¶

「決済金額検証」APIが正常に呼び出されるには、まず検証キーを発行する対象であるエンドポイントURLをHive コンソールに登録する必要があります。Hive サーバーでは、そのURLに商品ID、価格情報、クーポンコードなどを配信して検証キーを要求できます。

Hiveコンソール > コミュニティ&ウェブショップ > ウェブショップ > ウェブショップ設定 > 決済金額検証で決済有効性検証設定に従いAPIエンドポイント（コールバックURL）を登録します。

コールバックURL形式はゲーム会社が自由に設定可能
その他のAPI仕様は下記のAPIリクエスト構成およびAPIレスポンス構成項目に従う

API呼び出し（Hive サーバー → アプリサーバー）¶

Hive サーバーからアプリサーバーへの「決済金額検証」API呼び出し方式を説明します。

Request info¶

エンドポイント：Hiveコンソール > コミュニティ&ウェブショップ > ウェブショップ > ウェブショップ設定 > 決済金額検証で設定したエンドポイント（コールバックURL）
HTTPメソッド：POST

Request header¶

API情報	説明
Response Format	JSON
Content-type	application/json

Request body¶

名称	タイプ	必須有無（必須：O、オプション：X）	説明
game_index	Integer	O	ゲーム固有識別子
cs_code	String	O	購入したユーザーのPlayerID
language	String	O	言語コード（例：ko、en、ja）
market_pid	String	O	Hive コンソールウェブショップ > 商品管理に登録した商品ID
quantity	Integer	O	購入数量
original_price	Integer	O	商品元の金額
sale_price	Integer	O	割引適用後金額
coupon_price	Integer	O	クーポン割引金額
final_price	Integer	O	クーポンおよび割引適用後最終決済金額
discount_coupon_code	String	O	適用された割引クーポンコード（クーポン未使用時は未配信）

Request body sample¶

{
    "game_index": 1001,
    "cs_code": "20000010000",
    "language": "ko",
    "market_pid": "item01",
    "quantity": 1,
    "original_price": 10000,
    "sale_price": 8000,
    "coupon_price": 1000,
    "final_price": 7000,
    "discount_coupon_code": "SUMMER2025"
}

APIレスポンス（アプリサーバー → Hive サーバー）¶

「決済金額検証」API呼び出し結果としてアプリサーバーからHive サーバーへ送る応答情報を説明します。

Response body¶

データタイプ：JSON
パラメータ

名称タイプ説明

code Integer 結果コード（100：成功）

gameserver_price_verify_key String 決済検証時に使用される検証キー（成功時必須返却）

Response code¶

HTTPステータスコード	コード	メッセージ	説明
200	100	Success.	成功

成功は必ず100で配信してください。
成功時、gameserver_price_verify_keyを必ず含めて応答する必要があります。

Response sample¶

{
    "code": 100,
    "gameserver_price_verify_key": "a1b2c3d4e5f6g7h8i9j0"
}

名称	タイプ	説明
code	Integer	結果コード（100：成功）
gameserver_price_verify_key	String	決済検証時に使用される検証キー（成功時必須返却）