소비 정보 전송

앱 사용자가 환불 요청을 할 때 사용자 소비 정보를 앱 스토어에 전송하는 API를 제공합니다.

'소비 정보 전송' API는 Hive 서버와 앱 서버 간의 Server-to-Server 통신 방식으로 Hive 서버가 앱 서버로 소비 정보 전송 요청을 보내면, 앱 서버에서 응답값을 Hive 서버로 반환합니다.

동작 플로우¶

'소비 정보 전송' API 호출 및 응답의 전체 동작 흐름을 요약하면 아래와 같습니다.

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

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

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

API 엔드포인트 구성(서버 URL)¶

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

방화벽 규칙 해제¶

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

방화벽 규칙 해제 후, 아래 내용을 참고해 API 엔드포인트를 구성합니다.

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는 필수이며, 보내지 않으면 오류로 처리해 해당 건을 전송하지 않습니다.

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

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

응답 코드¶

전달 상태(delivery_status)¶

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

환불 선호도(refund_preference)¶

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