다음은 Windows OS 게임에서 PG 결제를 지원하기 위해 게임 서버에서 구현해야할 PG 결제 API입니다. Windows 환경에서 PG 결제에 관한 자세한 내용은 다음을 확인하세요.

결제 완료 내역 조회

결제 완료 시 결제 대행사(PG)는 Hive IAP v4 서버로 결제 결과를 직접 전달합니다. 이 방식은 네트워크의 불안전성을 보완하고 결제 데이터의 위변조를 방지합니다.
사전 작업 시 등록한 결제 정보와 결제 대행사(PG)의 정보를 대조하여 교차 검증을 수행합니다. 결제 정보의 무결성이 확인되면 추가적인 안전 장치를 확보하고, 결제 정보를 저장합니다. 저장된 결제 정보는 결제 완료 내역 조회 API를 통회 조회할 수 있습니다.
클라이언트에서는 이용자의 결제 완료 정보가 필요한 시점에 게임 서버에 정보를 요청하고, 게임 서버는 Hive IAP v4 서버를 통해 결제 정보를 조회합니다. 이용자의 결제 내역이 존재하는 경우 purchase_bypass_info를 활용하여 결제 정보 검증을 진행합니다.

Request URL

    상용 URL https://hiveiap.qpyou.cn/api_v4/purchases/unconsumed
    Sandbox URL https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed
    HTTP Method POST
    Content-Type application/json
    Data Format JSON
    Authorization Bearer (토큰)

Bearer 토큰은 Hive 콘솔 앱센터 > 프로젝트 관리 > 게임사 게임 선택 > 게임 상세 > 기본정보에서 Hive 인증키에 해당합니다.

Request Parameters

    명칭 타입 필수 여부
    (필수: M, 옵션: O)    		 설명
    appid String M Hive 콘솔 > 앱센터 에서 등록 및 발급 받은 ID
    market_id Number M 마켓 고유 ID (15 고정값 사용)
    server_id String M 결제가 발생한 게임서버 구분코드
    user_id_type String M HIVE 유저 타입
    uid : 개별모듈(v0)
    vid : 인증v1(v1)
    player_id : 인증v4(v4)
    user_id Number M HIVE 유저 ID
    user_id_type 에 따라 전송
    uid : 개별모듈(v0)
    vid : 인증v1(v1)
    player_id : 인증v4(v4)

Response Elements

    명칭 타입 필수 여부
    (필수: M, 옵션: O)    		 설명
    result Number M 응답 코드 (0: 성공)
    result_msg String M 응답 코드에 따른 결과 메시지
    unconsumed_lists Object Array M
    ┕ market_pid String M 상품 고유 ID
    ┕ order_id String M 주문번호
    ┕ server_id String M 구매한 유저가 접속한 게임서버 구분코드
    ┕ vid String M 구매한 유저의 PlayerID, v1 인증의 경우 VID
    ┕ uid String O 구매한 유저의 uid
    ┕ amount String M 결제 금액
    ┕ currency String M 결제 통화
    ┕ started_datetime Datetime M 결제를 시작한 시간 (Y-m-d H:i:s)
    ┕ paid_datetime Datetime M 결제를 완료한 시간 (Y-m-d H:i:s)
    ┕ hiveiap_receipt String M 결제 정보 암호화 HASH
    ┕ purchase_bypass_info String M 영수증 검증 요청에 필요한 필수 정보
    ┕ additionalInfo String O 게임 서버로 보내기 위해 클라이언트에서 전달받은 추가 정보 (JSON String 형식)
    (전달받은 정보가 없을 경우 null 반환)

Request Example

Response Example

결제 정보 검증

결제 결과 검증 API는 IAP v4 영수증 검증을 기반으로 합니다.

결제 결과 검증은 앞서 전달받은 purchase_bypass_info를 이용합니다. purchase_bypass_info는 결제 진행 전에 SDK를 통해 전달받은 각종 정보를 담고 있으며, Hive 애널리틱스로 전송됩니다.
영수증 검증 요청과 함께 매출로그의 전송이 필요하다면 game_info를 이용하세요. 전달받은 game_info는 Hive IAP에서 애널리틱스 서버로 로그 전송을 대행합니다.

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
    Content-Type text/html
    Data Format JSON
    Authorization Bearer (토큰)

Bearer 토큰은 Hive 콘솔 앱센터 > 프로젝트 관리 > 게임사 게임 선택 > 게임 상세 > 기본정보에서 Hive 인증키에 해당합니다.

Request Parameters

    명칭 타입 필수 여부
    (필수: M, 옵션: O)    		 설명
    purchase_bypass_info String M 영수증 대용 및 애널리틱스 전송용 데이터
    game_info Object Array O 게임로그, 매출로그와 같은 게임에 전달할 로그가 있을 때 이 값을 게임에 추가하여 전달하면 Hive IAP가 애널리틱스 서버에 전송을 대행한다. 영수증 검증 단계에서는 아이템 지급 완료(itemsendok) 여부를 알 수 없으므로 이 부분은 별도 구현하여 추가 정보로 제공해야 한다.
    ⠀⠀server_uid bigint O 게임서버에서 발급하는 user_id
    없으면 0
    ⠀⠀giftee_uid bigint O null: 본인 스스로 사용하기 위한 결제
    0: 선물 받은 사람이 있으나 UID 확인 불가 더비데이즈 게스트 계정은 허브 게스트 계정이 없으므로 여기에 해당
    ⠀⠀Level int O 유저의 게임 내 레벨
    레벨이 없을 경우는 불필요. 없으면 0.
    ⠀⠀character_id bigint O 서버 내에서 유니크한 캐릭터 구분 값 (PK?).
    캐릭터 개념이 없는 경우 “0”
    ⠀⠀character_type_id int O 캐릭터 타입 구분 값
    캐릭터 개념이 없는 게임은 “0” 입력
    ⠀⠀character_level int O 캐릭터 타입 구분 값
    캐릭터 개념이 없는 게임은 “0” 입력
    ⠀⠀is_emulator int O 블루스택 등 PC용 에뮬레이터로 접속 시 “1”, 그 외 “0” 입력

Response Elements

    명칭 타입 필수 여부
    (필수: M, 옵션: O)    		 설명
    result Number M 응답 코드 (Response Code 참고)
    result_msg String M 응답 코드에 따른 결과 메시지
    hiveiap_transaction_id String M 검증 성공한 영수증 별로 생성되는 트랜잭션 ID. 이 값을 게임 서버에 저장해서 게임이 영수증 중복 체크를 수행함
    hiveiap_market_id String O 마켓 고유번호 (PG 결제: 15 고정)
    hiveiap_market_pid String O 결제 상품 PID
    hiveiap_market_transaction_id String O 주문에 대한 고유 주문번호
    hiveiap_receipt String O 마켓 영수증 Object 값 (PG 결제: null 고정)
    hiveiap_purchase_test String O 테스트 결제 여부 (Y: 테스트 결제 / N: 일반 결제)

Response 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 영수증 검증에 실패 또는 해킹된 영수증인 경우
    (예: 스푸핑 해킹)
    1000507 Failed to save the purchase info 구매 이력 저장 실패
    1000524 Failed to authenticate the receipt. (not exist order) 영수증 검증 실패 (존재하지 않는 주문)
    1000525 Failed to authenticate the receipt. (wrong param) 영수증 검증 실패 (파라미터 오류)

Request Example

Response Example

지급 결과 처리

지급 결과 처리 API는 IAP v4 아이템 지급 결과 전송을 기반으로 합니다. 지급 결과 처리 API를 통해 아이템 구매부터 지급 완료까지의 결제 처리를 최종 마무리하게 됩니다. 결제 처리가 완료되지 않으면 유저는 동일 상품을 구매할 수 없습니다. 구매를 시도하여 결제 페이지로 진입하면 ‘이미 보유한 상품입니다.’라는 메시지가 노출되고 결제가 진행되지 않습니다.

여러 개의 결제창을 띄워 구매·결제를 시도하는 경우에도 결제 처리가 되지 않은 상품은 모두 자동 취소 처리됩니다. 게임 서버에서 진행하는 구매 횟수 제한 확인, 아이템 지급 등의 모든 결제 과정을 처리한 후 결제 결과를 전송하여 결제가 완료되었음을 Hive IAP v4 서버에 알립니다. 결제 취소를 요청하고자 하는 경우에도 지급 결과 처리 API를 통해 취소를 요청할 수 있습니다.

Request URL

    상용 URL https://hiveiap.qpyou.cn/api_v4/item_result
    Sandbox URL https://sandbox-hiveiap.qpyou.cn/api_v4/item_result
    HTTP Method POST
    Content-Type text/html
    Data Format JSON
    Authorization Bearer (토큰)

Bearer 토큰은 Hive 콘솔 앱센터 > 프로젝트 관리 > 게임사 게임 선택 > 게임 상세 > 기본정보에서 Hive 인증키에 해당합니다.

Request Parameters

    명칭 타입 필수 여부
    (필수: M, 옵션: O)    		 설명
    hiveiap_transaction_id String M 영수증 검증 결과의 hiveiap_transaction_id
    result_status Number M 아이템 지급 성공여부
    0: 지급 실패
    1: 지급 성공
    2: 결제 취소 환불 요청 (PG 전용)
    result_status_message String O 지급 실패 또는 결제 취소 요청 사유
    user_id_type String M Hive 유저 타입
    v0: 개별모듈 (uid)
    v1: 인증 v1 (vid)
    v4: 인증 v4 (player_id)
    user_id Number M 유저 ID
    user_id_type이 v0이면 uid를, v1이면 vid를, v4면 player_id를 전송
    asset Object Array O 지급한 아이템 정보
    지급 성공일 때만 값을 전달하고, 지급 실패일 때는 빈 array([])로 응답
    ⠀⠀asset_id String O 아이템 ID
    ⠀⠀asset_name String O 아이템 이름
    ⠀⠀quantity Number O 지급한 아이템 개수

Response Elements

    명칭 타입 필수 여부
    (필수: M, 옵션: O)    		 설명
    result Number M 응답 코드 (0: 성공)
    result_msg String M 응답 코드에 따른 결과 메시지

Request Example

Response Example

결제 결과 알림 서비스

결제 결과 알림 서비스는 결제 완료 또는 결제 취소가 발생하는 즉시 해당 결과를 게임 서버로 전송합니다. 이 API는 결제 완료 내역 조회와 동일하게 purchase_bypass_info 값을 전달하므로, 게임은 이 값을 사용해 영수증을 검증한 후 유저에게 상품을 지급할 수 있습니다. 결제 결과 전송 정보에서 type이 paid일 경우에만 영수증 검증과 상품 지급을 진행해야 합니다.

결제 결과 전송 기본 사항

    HTTP Method POST
    Content-Type application/json
    Data Format JSON

결제 결과 전송 정보

    명칭 타입 필수 여부
    (필수: M, 옵션: O)    		 설명
    type String M 알림 유형(paid: 결제 완료, cancelled: 결제 취소 또는 환불)
    market_pid String M 상품 고유 ID
    order_id String M 주문번호
    server_id String M 구매한 유저가 접속한 게임 서버 구분코드
    vid Number M 구매한 유저의 PlayerID, v1 인증의 경우 VID
    vid_type String O SDK 버전에 따른 vid 유형 값(기본 v4)
    uid Number O 구매한 유저의 uid
    amount String M 결제 금액
    currency String M 결제 통화
    started_datetime Datetime M 결제를 시작한 시간 (Y-m-d H:i:s)
    paid_datetime Datetime M 결제를 완료한 시간 (Y-m-d H:i:s)
    cancelled_datetime Datetime O 결제가 취소 또는 환불된 시간 (Y-m-d H:i:s)
    cancelled_reason String O 결제가 취소 또는 환불된 사유
    hiveiap_receipt String M 결제 정보 암호화 HASH
    purchase_bypass_info String M 영수증 검증 요청에 필요한 필수 정보
    additionalInfo String O 게임 서버로 보내기 위해 클라이언트에서 전달받은 추가 정보입니다. JSON String 형식이며 전달받은 정보가 없으면 null을 반환합니다.

결제 결과 전송 예시 (결제 완료 시)

결제 결과 전송 예시 (결제 취소 시)