IAP v4 상품 소비 처리

상품 소비 처리 API는 소모성 상품 구매 건을 소비 처리하는 API입니다.

Google Play

Google Play¶

Google Play 소모성 상품 소비 API는 Google Play에서 결제한 소모성 상품 구매 건을 소비 처리하는 API로, Google Play Developer API의 consume 기능을 대행합니다. Google Play는 인앱 결제 후 일정 기간(예: 3일) 내에 소비 처리가 완료되지 않을 경우 결제 건을 자동 환불하므로, 앱 서버는 유저에게 아이템 지급을 완료한 후 즉시 이 API를 호출하여 소비 처리를 진행해야 합니다.

Google 마켓 계정 설정 사전 안내

Google Play 소모성 상품 소비 API를 사용하려면 Google Market Account 설정이 완료되어야 합니다.

중복 호출 주의

본 API는 영수증 1건당 1회만 호출해야 합니다. 이미 소비 처리가 완료된 영수증으로 재호출할 경우 result 응답 코드로 1000535(Market API response was answered as failed.)가 반환됩니다.

Request URL¶

항목	내용
상용 URL	`https://hiveiap.qpyou.cn/external/api/finalize_purchase`
Sandbox URL	`https://sandbox-hiveiap.qpyou.cn/external/api/finalize_purchase`
HTTP Method	`POST`
HTTP Header	`Content-Type`: `application/json` `Authorization`: `Bearer {API_KEY}` (※ `Bearer` 토큰은 앱 센터 > 프로젝트 관리 > 게임 목록 > 게임 선택 > 게임 상세 > 기본 정보의 하이브 인증키 값입니다.)
Data Format	`JSON`

Request body¶

필드명	타입	필수	설명
`purchase_bypass_info`	String	Y	Hive SDK에서 추출한 구매 유저, 단말 및 영수증 정보입니다. IAP v4 인앱 구매 시 Hive SDK v4 `IAPV4` 클래스의 `Purchase()` 또는 `Restore()` 메서드 콜백으로 전달받은 `IAPV4Receipt` 객체의 `bypassInfo`(Base64로 인코딩된 JSON 문자열)를 'Hive SDK v4 → 앱 클라이언트 → 앱 서버 → IAP v4 구글 소모성 상품 소비 API 서버' 순으로 전달합니다. ※ 해당 값은 원본 그대로 사용해야 하며, 앱 클라이언트나 앱 서버에서 직접 파싱하거나 수정하지 않아야 합니다.

Response body¶

필드명	타입	필수	설명
`result`	Integer	Y	응답 코드 (`0`: 성공, 그 외: 실패. 세부 코드는 아래 Result codes 참고)
`result_msg`	String	Y	응답 메시지
`finalize_result`	Array	N	소비 처리 결과 목록입니다. (참고용 정보이며, 앱 서버의 아이템 지급 성공/실패 판정 로직에 사용해서는 안 됩니다.)
└ `market_transaction_id`	String	N	소비 처리를 시도한 마켓 트랜잭션(주문) ID
└ `result_code`	Integer	N	Google Play Developer API에서 응답한 소비 처리 결과 코드
└ `result_message`	String	N	Google Play Developer API에서 응답한 소비 처리 결과 메시지

Result codes¶

Code	Message	설명
`0`	Success	소비 처리 성공
`1000006`	The required parameter info is missing.	필수 파라미터가 누락된 경우
`1000504`	The Google public key hasn't been registered.	Google 서비스 계정키 정보가 등록되지 않은 경우
`1000520`	Failed to authenticate the API Key.	앱 센터에서 발급한 `Bearer` 토큰 인증 실패
`1000535`	Market API response was answered as failed.	Google Play Developer API 응답 결과가 실패인 경우 (※ `finalize_result` 하위의 `result_code` 및 `result_message`에서 상세 사유 확인 가능)

Request example¶

curl -L -v \
-d '{"purchase_bypass_info":"eyJ1aWQiOiIiLCJhbmFseXRpY3NfaWQiOiJqbXRsZkcwb1FZQzdlM3dVVDQ2cHJ3PT0i...(생략)..."}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAzNzc4OTU2LCJqdGkiOiIxODczMTExMzIwIn0.OxWo4R6UdI0BLP1ckt8RlMFrPAb5H7TNedmLFV1Cawc" \
[https://sandbox-hiveiap.qpyou.cn/external/api/finalize_purchase](https://sandbox-hiveiap.qpyou.cn/external/api/finalize_purchase)

Response example¶

{
  "result": 1000535,
  "result_msg": "Market API response was answered as failed.",
  "finalize_result": [
    {
      "market_transaction_id": "GPA.3373-7176-8955-08026",
      "result_code": 400,
      "result_message": "The product purchase is not owned by the user."
    }
  ]
}