웹 상점 구매 제한 검증 API

'웹 상점 구매 제한 검증'은 웹 상점에서 결제한 상품이 최대 구매 수량을 초과했는지 검증하는 기능입니다. Hive 서버에서는 해당 기능으로 웹 상점 결제 정보 검증 API를 제공합니다.

사전 준비¶

웹 상점 결제 정보 검증 API를 호출하기에 앞서 Hive 콘솔에서 최대 구매 수량을 설정합니다.

• Hive 콘솔 > 커뮤니티 & 웹 상점 > 웹 상점 > 상품 관리에서 구매 수량 제한 검증 설정을 통해 웹 상점 상품에 계정별 구매 제한과 구매 수량 제한을 설정합니다.
  • 계정별 구매 제한과 구매 수량 제한 각각에 최대 구매 수량을 설정할 수 있습니다.

동작 플로우¶

'웹 상점 구매 제한 검증'의 전체 동작 과정을 단계별 동작 주체를 중심으로 설명하면 아래와 같습니다. 본 문서에서는 아래 과정 중 2 단계에 해당하는 '웹 상점 결제 정보 검증 API' 호출 방법을 설명합니다.

1. 앱: 웹 상점에서 PG 결제 시 앱 서버에서 상품을 지급하는 프로세스를 구축합니다. 관련 설정은 결제 알림 설정을 참고하세요.

2. 앱 서버: 웹 상점에서 사용자가 구매 수량 제한 상품을 구매한 경우, 상품 지급 전에 웹 상점 결제 정보 검증 API를 호출하여 최대 구매 수량을 초과했는지 검증을 요청합니다.

3. Hive 서버: 사용자의 상품 주문에서 해당 상품의 최대 구매 수량을 초과했는지 검증합니다. 검증 후 결과를 API 응답값으로 앱 서버에 전송합니다.

4. 앱 서버: API 응답값을 확인한 후 검증 요건(예: 최대 구매 수량을 초과했는지 여부)을 통과했을 때에만 상품을 지급합니다. 만약 최대 구매 수량을 초과한 구매 주문이라면 상품을 지급하지 않고 결제를 취소 처리합니다. 웹 상점은 검증 결과에 문제가 없을 때에만 판매 완료 수량으로 반영한 후 상품의 잔여 수량을 감소시킵니다. API 응답값을 확인했을 때 유효하지 않은 결제로 나타난 경우, 앱 서버에서는 상품을 사용자에게 지급하지 말고 결제 취소 처리를 해야 합니다.

웹 상점 결제 정보 검증 API¶

웹 PG 결제가 완료된 결제 정보를 기준으로 구매하려는 상품의 최대 구매 수량 초과 여부를 검증하여 해당 결제의 유효성을 판단합니다.

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¶

• result_code 100, 101 응답에만 상품을 정상 지급해야 합니다.
• result_code 3001 응답은 이미 검증 완료된 주문 건입니다. 기존에 상품이 지급되지 않았던 경우에만 지급해야 합니다.
• result_code 3002 응답은 상품의 최대 구매 수량을 초과한 경우로, 반드시 해당 주문을 결제 취소해야 합니다. 자세한 사항은 지급 결과 처리를 참고하세요.

Response body sample¶

성공¶

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

JWT 검증 실패¶

{
  "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¶

API 호출 후 반환되는 응답 코드(result_code) 명세는 아래와 같습니다.