영수증 검증 API는 인앱 구매된 영수증에 대해 검증을 수행 후 영수증의 정상여부를 검증 결과로 응답합니다. 응답값의 hiveiap_transaction_id는 영수증별로 유니크하게 발급되는 ID이기 때문에 이 값을 게임서버에 저장하고 영수증이 중복되었는지 체크 후 아이템을 지급합니다.
Hive IAP v4 영수증 검증 API를 사용하여 검증하고 모든 Request Parameter의 모든값을 전송하면 매출정보 및 매출에 대한 게임정보의 애널리틱스 전송을 Hive IAP 서버에서 대행하며, 또한 Hive One 통합조회의 결제조회를 위한 API를 게임에서 따로 개발할 필요가 없습니다.

  • Request URL
    상용 URL https://hiveiap-verify.qpyou.cn/api_v4/verify
    Sandbox URL https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify
    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 클래스의 Purchase() 또는 Restore() 메서드에서 콜백한 IAPV4Receipt 객체의 bypassInfo(Base64로 인코딩한 JSON 형태의 값)를 Hive SDK v4 → 게임 클라이언트 → 게임서버 → Hive IAP v4 영수증 검증 서버 순으로 전달
    (게임팀에서 애널리틱스 필수 정보 추출에 필요한 공수를 줄이고, 영수증 JSON 직렬화 오류로 인한 문제 발생을 줄이기 위해 추가)    		 String Y
    market_id 마켓 ID(애플 앱스토어: 1 , 구글 플레이스토어: 2 , 러비:3 , 원스토어: 4) (SDK 4.6.0 이후 deprecated) Integer Y
    appid AppID (SDK v4.6.0 이후 deprecated) String Y
    appversion APP VERSION(애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    did 구매한 유저의 기기 식별자(애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    hive_country HIVE SDK에서 전달한 IP로 판단한 국가코드, ISO 3166-1(애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    country 단말 국가코드 (애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    client_ip Client IP (애널리틱스 전송용) String N
    language 단말 언어코드, ISO 639-1 Alpha-2 (애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    game_language 유저가 선택한 게임의 언어코드. ISO 639-1 Alpha-2 (애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    vid 구매한 유저의 PlayerID, v1 인증의 경우 VID (SDK v4.6.0 이후 deprecated) String Y
    uid 구매한 유저의 uid(SDK v4.6.0 이후 deprecated) String N
    server_id 구매한 유저가 접속한 게임서버 구분코드 (SDK v4.6.0 이후 deprecated) String N
    device_model 구매된 유저의 단말 모델 정보(애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    os_version 구매된 유저의 단말 OS 버전(애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    sdk_version 게임에서 적용한 Hive SDK Version (애널리틱스 전송용) (SDK v4.6.0 이후 deprecated) String N
    hiveiap_receipt 마켓에서 받은 영수증 데이터, hive.IAPV4.purchase()에서 콜백 응답한 IAPV4Receipt 객체안의 hiveiapReceipt 필드값 사용 (SDK v4.6.0 이후 deprecated) String Y
    price 구매한 금액, hive.IAPV4.purchase()에서 콜백 응답한 IAPV4Receipt 객체안의 IAPV4Product 객체의 price 필드값 사용 (SDK v4.6.0 이후 deprecated) Double Y
    currency 구매한 화폐 코드, hive.IAPV4.purchase()에서 콜백 응답한 IAPV4Receipt 객체안의 IAPV4Product 객체의 currency 필드값 사용 (SDK v4.6.0 이후 deprecated) String Y
    game_info 게임로그. 매출로그와 같이 게임에 전달할 로그가 있을 때 이 값을 게임에 추가해서 전달하면 Hive IAP가 애널리틱스 서버에 전송을 대행한다.
    영수증 검증 단계에서는 아이템 지급 완료(itemsendok) 여부를 알 수 없으므로, 이 부분은 별도 구현하여 추가 정보로 제공해야 한다. (IAP v4 아이템 지급 결과 전송)

    server_uid 게임서버에서 발급하는 user_id. 없으면 0 bigint
    giftee_uid null: 선물이 아닌 본인 사용하려고 결제
    0: 선물 받은 사람이 있으나 UID 확인 불가 (더비데이즈 게스트 계정은 허브 게스트 계정이 없으므로 여기에 해당)    		 bigint
    level 유저의 게임 내 레벨(레벨이 없을 경우는 불필요)
    없으면 0    		 int
    character_id 서버 내에서 유니크한 캐릭터 구분 값 (PK?). 캐릭터 개념이 없는 경우 0을 입력. bigint
    character_type_id 캐릭터 타입 구분 값. 캐릭터 개념이 없는 게임은 0을 입력 int
    character_level 캐릭터 타입 구분 값. 캐릭터 개념이 없는 게임은 0을 입력 int
    is_emulator 블루스택 등 PC용 에뮬로 접속했으면 1, 아니면 0 int
    server_type 게임 서버 환경 구분 값.
    예: qa, dev, staging, production
    (Hive 애널리틱스 v2에 구매 로그를 보낼 때 server_type이 production 이외의 값을 전달하면 env 열이 "TEST"로 전달)    		 String
    		Object N
  • Response
    필드명 설명 타입 필수여부
    result 응답 코드.

    • 0: 검증 성공
      응답 코드가 0(검증 성공)이고 hiveiap_purchase_cancel_state 필드 값이 0(구매 상태)일 경우, 아이템 지급 후 트랜잭션 종료(transaction finish) 처리
      응답 코드가 0(검증 성공)이고 hiveiap_purchase_cancel_state 필드 값이 1(구매 취소 상태)일 경우, 아이템을 지급하지 않고 트랜잭션 종료 처리
    • 1000503: 검증 실패(해킹이나 영수증 변조 등 명백한 검증 에러로, 아이템을 지급하지 않고 마켓 트랜잭션 종료를 권장함)
    • 1000519: Hive SDK v4.12.0에 추가된 느린 결제(예. 편의점 결제) 시도 시 결제 대기(Pending) 상태로 전송되는 영수증. 결제 전 상태이고 결제 완료 후 완료 영수증이 추가 전달되기 때문에 어떠한 처리도 하지 않음
    • 그 외 코드: Hive IAP 검증 서버 또는 마켓 검증 서버 이상. 복구(Restore)로 처리
    		 Integer Y
    result_msg 응답 메시지 String Y
    hiveiap_transaction_id 검증 성공한 영수증 별로 생성되는 트랜잭션 ID. 이 값을 게임 서버에 저장해서 게임이 영수증 중복 체크를 수행함.
    응답코드가 0(검증 성공)일 때만 값을 전달함    		 String N
    hiveiap_receipt String으로 생성된 영수증을 object로 변환한 값.
    애플 앱스토어만 Object로 생성할 수 없어 String으로 전달됨.
    응답코드가 0(검증 성공)일 때만 값을 전달함    		 애플 앱스토어: String
    그 외 마켓: Object    		 N
    hiveiap_market_transaction_id 마켓의 영수증에서 생성된 주문번호.값이 공백일 경우도 있어 이값으로 중복체크 하면 안되며 결제 참고용 데이터로만 사용
    응답코드가 0(검증 성공)일 때만 값을 전달함    		 String N
    hiveiap_receipt_verify_result 마켓 검증 서버에서 전달한 영수증 검증 결과. 응답코드가 0(검증 성공)일 때만 값을 전달함.

    ※ 해당 정보는 마켓 검증 서버의 추가 및 변경 등에 따라 결과 값이 달라질 수 있음.  
      해당 결과 값은 참고 용도로만 사용하여야 하며, 재화 또는 아이템의 지급 성공/실패를 판단하는 용도로 사용 금지.

    		 Object N
    hiveiap_market_pid 영수증 또는 영수증 검증결과에서 추출한 MARKET PID. hiveiap_market_pid 필드값으로 지급할 아이템을 판단하여 지급함, SDK에서 콜백으로 전달한 MARKET PID는 메모리 변조의 위험이 있어 그 값으로 사용하면 안됨. 응답코드가 0(검증 성공)일 때만 값을 전달함. String N
    hiveiap_market_id 결제된 마켓의 구분코드
    1: 애플 앱스토어
    2: 구글 플레이스토어
    3: 러비
    4: 원스토어
    응답코드가 0(검증 성공)일 때만 값을 전달함    		 Integer N
    hiveiap_purchase_cancel_state 구매 취소여부 (0: 구매상태, 1: 취소상태)
    마켓이 애플 앱스토어나 원스토어일 경우에만 취소 상태 판별 가능. 응답코드가 0(검증 성공)일 때만 값을 전달함    		 Integer N
    hiveiap_quantity 구매한 상품 수량 Integer N
    hiveiap_iap_payload 게임사에서 정의한 구매 메타 정보 String N
  • Result code
    Code Message Comment
    0 Success, Duplicate receipt 검증 성공
    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 Google public key hasn’t been registered 구글 영수증 검증을 위한 licence key가 등록되지 않았을 때
    1000505 The ONE Store appid hasn’t been registered 원스토어 영수증 검증을 위한 market appid가 등록되지 않았을 때
    1000507 Failed to save the purchase info 구매 이력 저장에 실패하였을 때
    1000512 Failed to authenticate the productId. 상품 검증 실패 (구매한 상품정보와 마켓 영수증의 정보가 일치하지 않거나 존재하지 않을 경우)
    1000516 The receipt verify server is abnormal. 마켓 영수증 검증 서버에 이상이 있을 경우
    1000519 Pending state Receipt. 느린 결제(예. 편의점 결제) 시도 시 결제 대기(Pending) 상태로 전송되는 영수증. 결제 전 영수증이기 때문에 어떠한 처리도 하지 않음
    1000520 Failed to authenticate the API Key. 앱센터에서 발급한 Bearer 토큰 검증 실패
    1000522 The Galaxy Store secret hasn’t been registered. 갤럭시 스토어 secret key 미등록 상태인 경우
    1000523 Failed to authenticate the receipt. (unexpected system error from Samsung IAP Server) 영수증 검증 실패 (삼성 IAP 서버의 예상치 못한 시스템 에러)
    1000524 Failed to authenticate the receipt. (not exist order) 영수증 검증 실패 (존재하지 않는 주문)
    1000525 Failed to authenticate the receipt. (wrong param) 영수증 검증 실패 (파라미터 오류)
    1000540 App Store Connect information not found. App Store Connect API 키 정보가 등록되지 않은 경우
  • 호출
    Apple(StoreKit1)

    Apple(StoreKit2)

    Google

    Hive Lebi

    ONE store

    Galaxy Store

    Facebook

    Huawei

    VIVO

    OPPO

    XIAOMI

  • 요청
    Apple(StoreKit1)

    Apple(StoreKit2)

    Google

    Hive Lebi

    ONE store

    Galaxy Store

    Facebook

    Huawei

    VIVO

    OPPO

    XIAOMI

  • 응답
    Apple(StoreKit1)

    Apple(StoreKit2)

    Google

    Hive Lebi

    ONE store

    Galaxy Store

    Facebook

    Huawei

    VIVO

    OPPO

    XIAOMI