구독 영수증 검증은 구독 상품을 구매했을 때 영수증을 검증한 후 영수증 검증 결과와 마켓별 영수증을 식별할 수 있는 식별키를 응답합니다.

마켓별로 구독 프로세스가 조금씩 다르기 때문에 모든 마켓을 동일 방식으로 대응할 수 없으며, 영수증 식별키인 hiveiap_apple_info(Apple), hiveiap_google_info(Google), hiveiap_amazon_info(Amazon), hiveiap_huawei_info(Huawei), hiveiap_onestore_info(원스토어) 응답 정보에 따라 다르게 대응해야 합니다.

  • 구독 구매 및 구매 복구
  • 구독 영수증 갱신 검증 스케쥴링

 

 

  • Request URL
    상용 URL https://hiveiap.qpyou.cn/api_v4/verify_subscription
    Sandbox URL https://sandbox-hiveiap.qpyou.cn/api_v4/verify_subscription
    HTTP Method POST
    HTTP Header Content-Type text/html
    Authorization Bearer (선택사항)

    • Hive 콘솔 앱센터 > 게임관리 > 게임목록 – 게임사 게임 선택 > 게임상세 > 기본정보에서 Hive 인증 상태가 Y일때만 Bearer 토큰을 사용할 수 있습니다.
    • Bearer 토큰은 앱센터 > 게임관리 > 게임목록 – 게임사 게임 선택 > 게임상세 > 기본정보에서 Hive 인증키에 해당합니다.
    Data Format JSON
  • Request
    필드명 설명 타입 필수여부
    purchase_bypass_info Hive SDK에서 추출한 구매 유저, 단말과 영수증 정보.
    Hive IAP v4 인앱 구매 시, Hive SDK v4 IAPV4 클래스의 purchaseSubscriptionupdate() 또는 restoreSubscription() 메서드에서 콜백한 IAPV4Receipt 객체의 bypassInfo(Base64로 인코딩한 JSON 형태의 값)를 Hive SDK v4 → 게임 클라이언트 → 게임서버 → Hive IAP v4 구독 영수증 검증 서버 순으로 전달
    String Y
  • Response
    필드명 설명 타입 필수여부
    result 응답 코드

    • 0: 검증 성공
    • 그 외 코드: 검증 실패 또는 Hive IAP 설정 이상
    Integer Y
    result_msg 응답 메시지 String Y
    hiveiap_market_id 결제된 마켓의 구분 코드

    • 1: Apple App Store
    • 2: Google Play Store
    • 5: Amazon Store
    • 7: Huawei Store

    응답 코드가 0(검증 성공)일 때만 값을 전달함

    Integer N
    hiveiap_receipt String으로 생성된 영수증을 object로 변환한 값
    Apple App Store만 object로 생성할 수 없어 string으로 전달됨
    응답코드가 0(검증 성공)일 때만 값을 전달함
    Apple App Store: String
    Google Play Store: Object
    N
    hiveiap_receipt_verify_result 마켓 검증 서버에서 전달한 영수증 검증 결과

    응답코드가 0(검증 성공)일 때만 값을 전달함

    Object N
    hiveiap_receipt_start_date_ms 구독 시작 시간 (Unix TimeStamp Milliseconds).
    응답코드가 0(검증 성공)일 때만 값을 전달함
    Long N
    hiveiap_receipt_expire_date_ms 구독 만료 시간 (Unix TimeStamp Milliseconds).
    응답코드가 0(검증 성공)일 때만 값을 전달함
    Long N
    hiveiap_receipt_subscription_state 구독 상태

    • 0: 정상 구독
    • 1: 결제 유예
    • 2: 결제 보류
    • 3: 일시 중지
    • 4: 만료

    현재 Google 구독의 경우만 값을 전달(Google외 마켓은 0으로 응답)하며, 2020년 11월 1일부터 Google 구독 결제 보류(account holding) 안내 및 구독 복원 지원이 2020년 11월 1일부터 필수 사항으로 Google 정책이 변경되어 구독 상태 확인을 목적으로 추가됨

    • 결제 유예(grace period): 유저 결제 상태가 정상화될 때까지 만료 시간을 연장함 (Google 마켓 콘솔에 설정한 유예 시간 동안 적용)
    • 결제 보류(account holding): 유저 결제 상태가 정상화되지 않은 상태에서 만료 시간이 지나 컨텐츠 권한이 부여되지 않으나, 결제 상태가 정상화된 후 구독을 복원했을 때 구독 만료시간이 연장됨(최대 30일간 결제 보류 상태 유지)
    Integer N
    hiveiap_apple_info Apple 구독 영수증 검증 결과에서 영수증을 식별할 수 있는 키 정보로 응답함. App Store 구독 영수증일 경우만 해당함.
    응답코드가 0(검증 성공)일 때만 값을 전달함.
    Object N
    ㄴ original_transaction_id 애플 구독 영수증을 식별 가능한 키.
    마켓 계정에서 동일 상품이나 동일 그룹 내 상품은 업그레이드, 다운그레이드, 취소 또는 재구매되어도 항상 동일한 값을 반환함(16자이며 Apple 가이드에 길이 설명이 없어 변동 가능함).
    String N
    hiveiap_google_info Google 구독 영수증 검증 결과에서 영수증을 식별할 수 있는 key정보로 응답함.
    Play Store 구독 영수증일 경우만 해당함.
    응답코드가 0(검증 성공)일 때만 값을 전달함.
    Object N
    ㄴ purchase_token 영수증의 구매 토큰 (200자 이상이며 Google 가이드에 길이 설명이 없어 변동 가능함) String N
    ㄴ purchase_token_hash purchase_token 필드 값을 해싱하여 생성한 값(sha1).
    purchase_token 값이 길어 게임에서 DB 저장과 조회에 어려움이 예상되기 때문에 해싱 후 제공함(40자).
    String N
    ㄴ linked_purchase_token 업그레이드, 다운그레이드, 구독 취소 또는 인앱에서 재활성화했을 때 구독 영수증이 신규 발행되면 이 필드 값으로 구 영수증의 구매 토큰을 식별할 수 있음.
    값이 있을 경우 구 영수증을 강제 만료시키도록 권장함(200자 이상이며 Google 가이드에는 길이 설명이 없어 변동 가능함).
    단, Play Store에서 재활성화 했을 때는 신규 발행되지 않음.
    String N
    ㄴ linked_purchase_token_hash linked_purchase_token 필드 값을 해싱하여 생성한 값(sha1).
    linked_purchase_token 값이 길어 게임에서 DB 저장과 조회에 어려움이 예상되기 때문에 해싱 후 제공함(40자).
    String N
    hiveiap_amazon_info Amazon 구독 영수증 검증 결과에서 영수증을 식별할 수 있는 key정보로 응답함.
    응답코드가 0(검증 성공)일 때만 값을 전달함
    Object N
    ㄴ receipt_id 구매 영수증 번호 String N
    hiveiap_huawei_info Huawei 구독 영수증 검증 결과에서 영수증을 식별할 수 있는 key정보로 응답함.
    응답코드가 0(검증 성공)일 때만 값을 전달함
    Object N
    ㄴ pay_order_id 구매 영수증 번호
    자동 결제될 때마다 값이 변경됨
    String N
    ㄴ purchase_token 영수증의 구매 토큰 (92자 이상이며 Huawei 가이드에 길이 설명이 없어 변동 가능함)
    구독 그룹 구매 기능을 지원하지 않는 상태에서는 자동 결제되더라도 기존 구매를 진행했던 마켓 계정과 상품이 동일할 경우 토큰 또한 동일한 값으로 유지됨
    String N
    ㄴ purchase_token_hash purchase_token 필드 값을 해싱하여 생성한 값(sha1) String N
    hiveiap_onestore_info 원스토어 구독 영수증 검증 결과에서 영수증을 식별할 수 있는 key정보로 응답함.
    응답코드가 0(검증 성공)일 때만 값을 전달함
    Object N
    ㄴ purchase_id 구매 영수증 번호
    자동 결제될 때마다 값이 변경됨
    String N
  • Result code
    코드 메시지 설명
    0 Success 검증 성공
    1000001 No requested parameter 전송된 파라미터가 없을 때
    1000003 DB Connection Error DB Connection이 안 될 때
    1000005 Internal Server Error 내부 서버 에러
    1000006 The required parameter info is missing 필수 파라미터 값이 없을 때
    1000503 Failed to authenticate the receipt 영수증 검증 실패 또는 해킹된 영수증일 때(스푸핑 해킹)
    1000504 The public key hasn’t been registered Google, Amazon, Huawei, 원스토어 영수증 검증에 필요한 license key가 등록되지 않았을 때
    1000507 Failed to save the purchase info 구독 검증 이력 저장에 실패하였을 때
    1000516 The receipt verify server is abnormal 마켓 영수증 검증 서버에 이상이 있을 경우
    1000517 Failed to find the Google API private key Google Developer API 호출에 필요한 서비스 계정이 앱센터에 등록되지 않았을 때
    1000518 Failed to find the shared secret key Apple 구독 검증에 필요한 shared secret key가 앱센터에 등록되지 않았을 때
    1000520 Failed to authenticate the API Key 앱센터에서 발급한 Bearer 토큰 검증 실패
    1000540 App Store Connect information not found. App Store Connect API 키 정보가 등록되지 않은 경우

 


    • 호출 예제
      Apple App Store

      Google Play Store

      Amazon Appstore

      Gallaxy Store

      Huawei AppGallery

      ONE store

    • 요청 예제
Apple App Store

Google Play Store

Amazon Appstore

Gallaxy Store

Huawei AppGallery

ONE store

    • 응답 예제
Apple App Store

Google Play Store

Amazon Appstore

Gallaxy Store

Huawei AppGallery

ONE store