소비 정보 전송

Apple App Store¶

스토어에 전송할 소비 정보에는 앱 서버에만 존재하는 데이터도 있습니다. 따라서 Hive 서버가 이 데이터를 Apple App Store에 전송하려면, 앱 서버에서 Hive 서버에 데이터를 전달해줘야 합니다.

앱 서버 URL은 앱 서버가 Hive 서버에 데이터를 전달하기 위해, 앱 서버에서 열어놓은 API 엔드포인트입니다. 아래 규약에 따라 API 엔드포인트를 구성한 후 이를 앱 서버 URL에 등록하시면, 사용자가 환불 요청을 할 때마다 Hive 서버가 이 API 엔드포인트로 POST 요청을 하고 필요한 데이터를 앱 서버로부터 전달받습니다. Hive 서버는 이 데이터를 취합해 앱 개발사를 대신해 Apple App Store에 소비 정보 전송을 완료합니다.

전체 과정을 요약하면 아래와 같습니다.

1. 앱: 아래 규약대로 API 엔드포인트를 구성해 서버 URL을 준비
2. 앱: Hive 콘솔의 부가 서비스 설정 > 소비 정보 전송에서 Apple App Store 사용을 선택하고 서버 URL을 등록
3. 앱 클라이언트: 앱을 실행한 상태에서 인앱 상품 소비 정보 전송에 동의
4. 앱 사용자: 앱에서 환불 요청
5. Apple: Hive 서버로 소비 정보 요청(CONSUMPTION_REQUEST) 발송
6. Hive 서버: 앱에서 등록한 서버 URL로 POST API 요청, 앱 서버로부터 응답값으로 소비 정보 데이터 수신
7. Hive 서버: Apple App Store에 소비 정보 전송(성공 시 Apple이 HTTP 202 응답)

방화벽 규칙 해제¶

서버 URL에 등록할 API 엔드포인트는 요청 매개변수의 사용자 정보(player_id)와 거래 정보(transaction_id)로 소비 정보를 조회하고, 아래 규약에 맞는 데이터를 응답으로 전달해야 합니다.

Hive 서버가 앱 서버 API 엔드포인트로 요청을 보낼 수 있도록, 앱 서버에서 아래 IP 주소에 대해 방화벽 인바운드 규칙을 해제해야 합니다.

API 요청(Hive 서버 → 앱 서버) 구성¶

Hive 서버에서 앱 서버로 보내는 POST 요청 정보입니다.

Request body¶

요청 본문 정보는 아래와 같습니다.

요청 본문 예시는 아래와 같습니다.

{
        "gameindex": 539,
        "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
        "server_id": "server_01",
        "player_id": "222333",
        "transaction_id": "2000000123456789"
}

API 응답(앱 서버 → Hive 서버) 구성¶

앱 서버는 처리 결과 코드(code), 결과 메시지(message), 소비 정보(data)를 Hive 서버로 전달합니다.

Response body¶

Hive 서버는 code 값으로 성공 여부를 판별합니다. 200이면 성공으로 보고 data를 사용하며, 그 외 코드는 해당 건을 전송하지 않고 message를 사유로 기록합니다. code는 필수이며, 보내지 않으면 오류로 처리해 해당 건을 전송하지 않습니다.

응답 코드¶

전달 상태(delivery_status)¶

소모성 아이템의 전달 상태를 나타내며, 아래 5개 값 중 하나여야 합니다(필수).

환불 선호도(refund_preference)¶

앱에서 선호하는 환불 처리 방향을 Apple에 전달합니다(선택). 값을 보낼 경우 아래 3개 중 하나여야 합니다.

응답 성공 시 응답 본문 예시는 아래와 같습니다.

{
        "code": 200,
        "message": "OK",
        "data": {
                "delivery_status": "DELIVERED",
                "refund_preference": "GRANT_FULL",
                "consumption_percentage": 100000,
                "sample_content_provided": 0
        }
}

Google Play¶

스토어에 전송할 소비 정보에는 앱 서버에만 존재하는 데이터도 있습니다. 따라서 Hive 서버가 이 데이터를 Google Play에 전송하려면, 앱 서버에서 Hive 서버에 데이터를 전달해줘야 합니다.

앱 서버 URL은 앱 서버가 Hive 서버에 데이터를 전달하기 위해, 앱 서버에서 열어놓은 API 엔드포인트입니다. 아래 규약에 따라 API 엔드포인트를 구성한 후 이를 앱 서버 URL에 등록하시면, 환불 심사 알림이 발생할 때마다 Hive 서버가 이 API 엔드포인트로 POST 요청을 하고 필요한 데이터를 앱 서버로부터 전달받습니다. Hive 서버는 이 데이터를 취합해 앱 개발사를 대신해 Google에 환불 심사 정보 전송을 완료합니다.

전체 과정을 요약하면 아래와 같습니다.

1. 앱: 아래 규약대로 API 엔드포인트를 구성해 서버 URL을 준비
2. 앱: Hive 콘솔의 부가 서비스 설정 > 소비 정보 전송에서 Google Play 사용을 선택하고 서버 URL을 등록
3. 앱 사용자: 결제 건에 대해 금융기관(카드사 등)에 직접 환불(차지백) 요청
4. Google: Hive 서버로 환불 심사 알림(pendingRefundReviewNotification) 발송
5. Hive 서버: 앱이 등록한 서버 URL로 POST API 요청, 응답값으로 데이터 수령
6. Hive 서버: Google에 환불 심사 정보 전송(orders:reviewrefund, 성공 시 HTTP 200 빈 본문)

방화벽 규칙 해제¶

서버 URL에 등록할 API 엔드포인트는 요청 매개변수의 사용자 정보(player_id)와 거래 정보(order_id)로 소비 정보를 조회하고, 아래 규약에 맞는 데이터를 응답으로 전달해야 합니다.

Hive 서버가 앱 서버 API 엔드포인트로 요청을 보낼 수 있도록, 앱 서버에서 아래 IP 주소에 대해 방화벽 인바운드 규칙을 해제해야 합니다.

API 요청(Hive 서버 → 앱 서버) 구성¶

Hive 서버에서 앱 서버로 보내는 POST 요청 정보입니다.

요청 본문 정보는 아래와 같습니다.

요청 본문 예시는 아래와 같습니다.

{
        "gameindex": 539,
        "appid": "com.com2us.hivesdk.normal.freefull.google.global.android.universal",
        "server_id": "server_01",
        "player_id": "222333",
        "order_id": "GPA.3300-1234-5678-90123"
}

API 응답(앱 서버 → Hive 서버) 구성¶

앱 서버는 처리 결과 코드(code), 결과 메시지(message), 소비 정보(data)를 Hive 서버로 전달합니다.

Hive 서버는 code 값으로 성공 여부를 판별합니다. 200이면 성공으로 보고 data를 사용하며, 그 외 코드는 해당 건을 전송하지 않고 message를 사유로 기록합니다. code는 필수이며, 보내지 않으면 오류로 처리해 해당 건을 전송하지 않습니다.

응답 코드¶

환불 선호도(refund_preference)¶

앱이 선호하는 환불 처리 방향을 Google에 전달합니다. 아래 4개 값 중 하나여야 합니다(필수).

소비 이벤트(consumption_usage_events)¶

각 소비 이벤트는 아래 필드로 구성합니다. 모든 필드는 선택이나, location을 보낼 경우 location.region_code는 필수입니다.

응답 성공 시 응답 본문 예시는 아래와 같습니다.

{
        "code": 200,
        "message": "OK",
        "data": {
                "refund_preference": "APPROVE",
                "sample_content_provided": 0,
                "consumption_percentage_milliunits": 100000,
                "consumption_usage_events": [
                        {
                                "consumption_time": "2026-07-20T00:00:00Z",
                                "ip_address": "203.0.113.10",
                                "consumption_item_description": "Sample consumed item",
                                "location": {
                                        "region_code": "KR"
                                }
                        }
                ]
        }
}