Skip to content

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 the Hive web shop server and game server is as follows:

  1. User action: When purchasing products with changed amounts in the Hive web shop, the 'Payment Amount Verification' API is called.
  2. Hive web shop server: Requests a verification key from the verification key issuance target URL (game server) registered in the Hive Console. At this time, product PID, price information, coupon code, etc. are delivered in callback format.
    • For the process of registering the verification key issuance target URL in the Hive Console, refer to the prerequisites below.
  3. Game server: After verifying the received price information, returns a verification key (gameserver_price_verify_key) to be used for payment verification as a response.
  4. Hive web shop server: Performs payment amount verification by delivering the verification key received from the game server along with product PID and price information back to the game server through the billing server.
  5. Game server: When payment completion occurs on the billing server, verifies the validity of the received verification key and then provides the final products.

Prerequisites

For the 'Payment Amount Verification' API to be called normally, game companies must first register the endpoint URL for issuing verification keys in the Hive Console. The Hive web shop server can request verification keys by delivering product PID, 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.

  • 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 web shop server → Game server)

This explains how the 'Payment Amount Verification' API is called from the Hive server to the game 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

API Information Description
Response Format JSON
Content-type application/json

Request body

Name Type Required (Required: O, Optional: X) Description
game_index Integer O Game unique identifier
cs_code String O PlayerID of the purchasing user
language String O Language code (e.g., ko, en, ja)
market_pid String O Product unique ID
quantity Integer O Purchase quantity
original_price Integer O Original product amount
sale_price Integer O Amount after discount application
coupon_price Integer O Coupon discount amount
final_price Integer O Final payment amount after coupon and discount application
discount_coupon_code String O Applied discount coupon code (not delivered when coupon is not used)

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 (Game server → Hive web shop server)

This explains the response information sent from the game server to the Hive web shop 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

HTTP Status Code Code Message Description
200 100 Success. Success
  • 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"
}