결제 금액 검증 API

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

동작 플로우¶

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

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

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

사전 준비¶

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

하이브 콘솔 커뮤니티 & 웹 상점 > 웹 상점 > 웹 상점 설정 > 서비스 설정 > 결제 금액 검증에서 결제 유효성 검증 설정에 따라 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"
}