결제 금액 검증 API

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

동작 플로우¶

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

하이브 웹 상점 서버, 게임 서버 간의 동작 및 데이터 흐름은 아래와 같습니다.

1. 사용자 액션: 하이브 웹 상점에서 변경된 금액의 상품을 구매 시 '결제 금액 검증' API가 호출됩니다.
2. 하이브 웹 상점 서버: 하이브 콘솔에 등록된 검증키 발급 대상 URL(게임 서버)로 검증키를 요청합니다. 이 때 상품 PID, 가격 정보, 쿠폰 코드 등을 콜백 형태로 전달합니다.
   • 하이브 콘솔에 검증키 발급 대상 URL을 등록하는 과정은 아래 사전 준비 사항을 참고하세요.
3. 게임 서버: 전달받은 가격 정보를 검증한 후 결제 검증에 사용될 검증키(gameserver_price_verify_key)를 응답으로 반환합니다.
4. 하이브 웹 상점 서버: 게임 서버로부터 응답 받은 검증키와 함께 상품 PID 및 가격 정보 등을 빌링 서버를 거쳐 다시 게임 서버로 전달함으로써 결제 금액 검증을 수행합니다.
5. 게임 서버: 빌링 서버에서 결제 완료가 이루어지면 전달받은 검증키 유효성을 확인 후 최종 상품을 지급합니다.

사전 준비¶

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

하이브 콘솔 > 커뮤니티 & 웹 상점 > 웹 상점 > 웹 상점 설정 > 결제 금액 검증에서 API 엔드포인트(콜백 URL)를 등록합니다.

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

API 호출(하이브 웹 상점 서버 → 게임 서버)¶

하이브 서버에서 게임 서버로 '결제 금액 검증' 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 응답(게임 서버 → 하이브 웹 상점 서버)¶

'결제 금액 검증' API 호출 결과로 게임 서버에서 하이브 웹 상점 서버로 보내는 응답 정보를 설명합니다.

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"
}