Payment amount validation API

The 'Payment Amount Verification' API supports verifying discounted payment amounts using verification keys issued by the game server when users want to purchase products with changed amounts due to web shop product discounts or coupon applications. When payment is made with a valid verification key, the game server can ultimately provide the products.

Operation flow¶

This explains the overall processing sequence and inter-system processing from calling the 'Payment Amount Verification' API to final product provision.

The operation and data flow between Hive Server and the app server is as follows:

1. User action: The 'Payment Amount Verification' API is called when purchasing a product with a discounted amount due to a discount or coupon applied in the Hive web shop.
2. Hive Server: Requests a verification key from the API (app server) registered in Hive Console Payment Amount Verification. Product ID, price information, coupon code, etc. are delivered in callback format.
   • Registering the payment amount verification API in Hive Console: see Prerequisites below
3. App server: After verifying the received product ID and price information, returns a verification key (gameserver_price_verify_key) to be used for payment verification as a response.
4. Hive Server: Delivers the verification key received from the app server along with product ID and price information to the billing server to request payment.
5. App server: Verifies the verification key, product ID, price information, etc. delivered as the billing server payment completion result. Considers the payment valid only when the received verification key matches the value verified and issued in step 3. Provides products only if verification succeeds.
   • For products with per-account purchase limit or purchase quantity limit settings: see Web shop purchase limit verification

Prerequisites¶

For the 'Payment Amount Verification' API to be called normally, first register the endpoint URL for issuing verification keys in Hive Console. Hive Server can request verification keys by delivering product ID, price information, coupon code, etc. to that URL.

Register the API endpoint (callback URL) in Hive Console > Community & Web Shop > Web Shop > Web Shop Settings > Payment Amount Verification according to the Payment Amount Verification settings.

• Callback URL format can be freely set by the game company
• Other API specifications follow the API request configuration and API response configuration items below

API call (Hive Server → app server)¶

This explains how the 'Payment Amount Verification' API is called from Hive Server to the app server.

Request info¶

• Endpoint: Endpoint (callback URL) set in Hive Console > Community & Web Shop > Web Shop > Web Shop Settings > Payment Amount Verification
• HTTP Method: POST

Request header¶

Request body¶

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 response (app server → Hive Server)¶

This explains the response information sent from the app server to Hive Server as a result of calling the 'Payment Amount Verification' API.

Response body¶

• Data type: JSON

• Parameters

  Name	Type	Description
  code	Integer	Result code (100: Success)
  gameserver_price_verify_key	String	Verification key to be used for payment verification (mandatory return on success)

Response code¶

• Success must be delivered as 100.
• On success, gameserver_price_verify_key must be included in the response.

Response sample¶

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