Web Shop Purchase Limit Validation API¶

'Web Shop purchase limit validation' verifies whether a product purchased in the Web Shop exceeds the maximum purchase quantity. Hive provides the Web Shop payment information validation API for this feature.

Prerequisites¶

Before calling the Web Shop payment information validation API, configure the maximum purchase quantity in Hive Console. In Hive Console > Community & Web Shop > Web Shop > Product Management, use purchase quantity limit validation settings to set per-account purchase limits and purchase quantity limits for Web Shop products. You can set a maximum purchase quantity for each setting.

Flow¶

1. App: Build a process in which the app server grants products when PG payment is made in the Web Shop. For related settings, see Payment notification settings.
2. App server: When a user purchases a purchase quantity limit product in the Web Shop, call the Web Shop payment information validation API before granting the product.
3. Hive server: Verifies whether the user order exceeds the product maximum purchase quantity, then sends the result to the app server as an API response.
4. App server: Grant the product only when the API response passes the validation requirements. If the order exceeds the maximum purchase quantity, do not grant the product and cancel the payment. The Web Shop reflects the quantity as sold and decreases the remaining quantity only when validation has no issues. If the API response indicates an invalid payment, the app server must not grant the product to the user and must cancel the payment.

Web Shop payment information validation API¶

Validates whether the payment is valid based on completed Web PG payment information, including whether the product exceeds the maximum purchase quantity.

Request information¶

Request header¶

Request header sample¶

Content-Type : application/json
X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0.eyJwcm9qZWN0X2lkIjoiY29tLmNvbTJ1cy5leGFtcGxlIiwidG9rZW5fdHlwZSI6ImFjY2Vzc190b2tlbiIsImdyYW50X3R5cGUiOiJwcm9qZWN0IiwiaWF0IjoxNzE1NTg0MDAwLCJleHAiOjE3MTU1ODc2MDAsImF1dGhfdmVyIjoidjQiLCJ1c2VyX2lkIjoiIiwiaXNfd2hpdGVsaXN0Ijp0cnVlfQ.signature

Request body¶

Request body sample¶

{
  "type": "paid",
  "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
  "order_id": "H3175513391360875943",
  "server_id": "1",
  "appid": "com.com2us.hivesdk.windows.hivepc",
  "cs_code": "20000023100",
  "paid_datetime": "2025-08-14 10:12:18",
  "quantity": "10",
  "iap_payload": "{"cs_code":20000023100,"data":{"server_id":"1","server_name":"Server 1","channels":{"channel_id":"11","channel_name":"Channel 11","characters":{"character_id":"111","character_name":"Character 111"}}}}"
}

Response body¶

• Products should be granted normally only for result_code responses 100 and 101.
• result_code 3001 is an already validated order. Grant the product only if it was not granted previously.
• result_code 3002 means the product maximum purchase quantity was exceeded. You must cancel the payment for that order. For details, see Grant result processing.

Response body sample¶

Success¶

{
  "result_code": 100,
  "result_msg": "success",
  "token_validation": {
    "result_code": 0,
    "result_msg": "success"
  }
}

JWT validation failure¶

{
  "result_code": 2499,
  "result_msg": "JWT validation failed. See token_validation for details.",
  "token_validation": {
    "result_code": 2408,
    "result_msg": "The access token is expired. Please refresh your token."
  }
}

Response code¶