결제 금액 검증 API

'결제 금액 검증' API는 사용자가 웹 상점 상품 할인 또는 쿠폰을 적용하여 변경된 금액의 상품을 구매하고자 할 때, 앱 서버에서 발급한 검증키를 이용하여 할인된 결제 금액을 검증하도록 지원합니다. 유효한 검증키를 통해 결제가 이루어지면 최종적으로 앱 서버에서 상품을 지급할 수 있습니다.

동작 플로우¶

'결제 금액 검증' API 호출부터 최종 상품을 지급하기까지 전체 처리 순서 및 시스템 간의 처리 과정을 설명합니다.

Hive 서버, 앱 서버 간의 동작 및 데이터 흐름은 아래와 같습니다.

1. 사용자 액션: Hive 웹 상점에서 할인 또는 쿠폰이 적용되어 할인된 금액의 상품을 구매할 때 '결제 금액 검증' API가 호출됩니다.
2. Hive 서버: Hive 콘솔 결제 금액 검증에 등록된 API(앱 서버)로 검증키를 요청합니다. 이때 상품 ID, 가격 정보, 쿠폰 코드 등을 콜백 형태로 전달합니다.
   • Hive 콘솔 결제 금액 검증 API 등록: 아래 사전 준비 참조
3. 앱 서버: 전달받은 상품 ID 및 가격 정보 등을 검증한 후 결제 검증에 사용될 검증키(gameserver_price_verify_key)를 응답으로 반환합니다.
4. Hive 서버: 앱 서버로부터 응답받은 검증키와 함께 상품 ID 및 가격 정보 등을 빌링 서버에 전달하여 결제를 요청합니다.
5. 앱 서버: 빌링 서버 결제 완료 결과로 전달된 검증키, 상품 ID, 가격 정보 등을 확인합니다. 전달받은 검증키가 3번에서 자신이 검증·발급했던 값과 일치할 때만 결제를 유효한 것으로 판단합니다. 검증에 성공한 경우에만 상품을 지급합니다.
   • 계정별 구매 제한·구매 수량 제한 설정 상품: 웹 상점 구매 제한 검증 참조

사전 준비¶

'결제 금액 검증' API가 정상적으로 호출되려면 먼저 검증키를 발급할 대상인 엔드포인트 URL을 Hive 콘솔에 등록해야 합니다. Hive 서버에서는 해당 URL로 상품 ID, 가격 정보, 쿠폰 코드 등을 전달하여 검증키를 요청할 수 있습니다.

Hive 콘솔 커뮤니티 & 웹 상점 > 웹 상점 > 웹 상점 설정 > 서비스 설정 > 결제 금액 검증에서 결제 유효성 검증 설정에 따라 API 엔드포인트(콜백 URL)를 등록합니다.

• 콜백 URL 형식은 앱에서 자유롭게 설정
• 그 외 API 스펙은 하단의 API 요청 구성 및 API 응답 구성 항목을 따름

API 호출(Hive 서버 → 앱 서버)¶

Hive 서버에서 앱 서버로 '결제 금액 검증' API 호출 방식을 설명합니다.

Request info¶

• Endpoint: 커뮤니티 & 웹 상점 > 웹 상점 > 웹 상점 설정 > 서비스 설정 > 결제 금액 검증에서 설정한 엔드포인트(콜백 URL)
• 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 응답(앱 서버 → Hive 서버)¶

'결제 금액 검증' API 호출 결과로 앱 서버에서 Hive 서버로 보내는 응답 정보를 설명합니다.

Response body¶

• Data type: JSON

• Parameters

  명칭	타입	설명
  code	Integer	결과 코드 (100: 성공)
  gameserver_price_verify_key	String	결제 검증 시 사용될 검증키 (성공 시 필수 반환)

Response code¶

• 성공은 반드시 100으로 전달하세요.
• 성공 시 gameserver_price_verify_key를 반드시 포함하여 응답해야 합니다.

Response sample¶

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