웹 PG 결제

웹 PG 결제 API는 Windows 앱 개발 시 Hive SDK 빌링을 사용하지는 않지만, 웹사이트에서 PG 결제를 구현하기 원할 때 사용하는 API입니다. 웹 PG 결제 API는 앱에서 PG 결제를 구현하는 API와는 다릅니다.

상품 목록 조회¶

상품 정보를 가져옵니다. 앱에서 상품 목록을 구현하는 데 사용합니다.

Request URL¶

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

Request parameters¶

Response elements¶

Request example¶

curl -L -v \
    -d '{"api": "product","market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid_type": "consumable"}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/product

Response example¶

{
    "result": 0,
    "result_msg": "success",
    "product_list": [
        {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
            "price": 1200,
            "currency": "KRW",
            "display_price": "₩1,200",
            "title": "크리스탈 한 줌",
            "description": "크리스탈 한 줌",
            "product_type": "consumable"
        }, {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item02",
            "price": 2500,
            "currency": "KRW",
            "display_price": "₩2,500",
            "title": "크리스탈 묶음",
            "description": "크리스탈 묶음",
            "product_type": "consumable"
        }, {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item03",
            "price": 3900,
            "currency": "KRW",
            "display_price": "₩3,900",
            "title": "크리스탈 더미",
            "description": "크리스탈 더미",
            "product_type": "consumable"
        }
    ],
    "update_date": "2022-10-28 16:11:23"
}

상품 주문 요청¶

상품 목록에서 선택한 PID(상품 ID) 정보로 상품 주문을 요청합니다.

Request URL¶

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

Request parameters¶

Request example¶

curl -L -v \
    -d '{"market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01","server_id": "KR1","os": "A","quantity": 1,"iap_payload": "{\"character_id\":\"hivesdk01\"}"}' \
    -H "Content-Type: text/html" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
    https://sandbox-store.withhive.com/external/api/order

Response example¶

상품 주문 요청이 정상적으로 처리되면 결제 수단을 선택하는 팝업창을 반환합니다. 아래 팝업창을 구성하는 HTML 페이지를 반환합니다.

결제 완료 내역 조회¶

결제 완료 시 결제 대행사(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	결제 통화
┕ quantity	Number	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¶

curl -L -v
 -d '{"appid" : "com.com2us.hivesdk.windows.microsoftstore.global.normal","market_id" : 15,"server_id" : "kr","user_id_type": "player_id", "user_id": 30000056996}' \
 -H "Content-Type: text/html" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed

Response example¶

{
    "result": 0,
    "result_msg": "SUCCESS",
    "unconsumed_lists": [
        {
            "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
            "order_id": "h2164792542890731850",
            "server_id": "kr",
            "vid": "30000056996",
            "uid": "13079",
            "amount": "1200",
            "currency": "KRW",
            "quantity": 1,            
            "started_datetime": "2022-03-22 14:03:49",
            "paid_datetime": "2022-03-22 14:04:39",
            "market_id": "15",
            "hiveiap_receipt": "2YnGzfTCGycoMjcSyYyNXBjANwmFyB6m\/c0bYazQ8VQ=",
            "purchase_bypass_info": "eyJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2R...",
            "additionalInfo": null
        }
    ]
}

결제 정보 검증¶

결제 결과 검증 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¶

curl -L -v \
 -d '{"purchase_bypass_info":"eyJtYXJrZXRfaWQiOiIxNSIsIm9yZGVyX2lkIjoiSDMxNjQ3OTI1NDI4OTA3MzE4NTAiLCJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2RrLndpbmRvd3MubWljcm9zb2Z0c3RvcmUuZ2xvYmFsLm5vcm1hbC5pdGVtMDEiLCJ2aWQiOiIzMDAwMDA1Njk5NiIsInVpZCI6IjEzMDc5Iiwic2VydmVyX2lkIjoia3IiLCJhcHBpZCI6ImNvbS5jb20ydXMuaGl2ZXNkay53aW5kb3dzLm1pY3Jvc29mdHN0b3JlLmdsb2JhbC5ub3JtYWwiLCJhbW91bnQiOiIxMjAwIiwic3RhcnRlZF9kYXRldGltZSI6bnVsbCwicGFpZF9kYXRldGltZSI6bnVsbCwiY3VycmVuY3kiOiJLUlciLCJoaXZlaWFwX3JlY2VpcHQiOiIyWW5HemZUQ0d5Y29NamNTeVl5TlhCakFOd21GeUI2bVwvYzBiWWF6UThWUT0ifQ=="}' \
 -H "Content-Type: text/html" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify

Response example¶

{
    "result": 0,
    "result_msg": "success",
    "hiveiap_transaction_id": "HS_13",
    "hiveiap_market_id": 15,
    "hiveiap_market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "hiveiap_market_transaction_id": "h2164792542890731850",
    "hiveiap_receipt": null,
    "hiveiap_purchase_test": "N"
}

지급 결과 처리¶

지급 결과 처리 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¶

curl -L -v
 -d '{"hiveiap_transaction_id" : "HS_13","result_status": 1,"user_id_type": "vid","user_id": 30000056996,"asset": [ {"asset_id":"item_id","asset_name":"item_name","quantity":1}
,{"asset_id":"item_id","asset_name":"item_name","quantity":1}]}' \
 -H "Content-Type: text/html" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
 https://sandbox-hiveiap.qpyou.cn/api_v4/item_result

Response example¶

{
    "result": 0,
    "result_msg": "success"
}

결제 결과 알림 서비스¶

결제 결과 알림 서비스는 결제 완료 또는 결제 취소가 발생하는 즉시 해당 결과를 게임 서버로 전송합니다. 이 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	결제 통화
quantity	Number	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을 반환합니다.

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

{
    "type": "paid",
    "market_id": "15",
    "order_id": "H2168993822440686730",
    "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "vid": "20000011337",
    "uid": "67200717",
    "vid_type": "v4",
    "server_id": "kr",
    "appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
    "amount": "1200",
    "started_datetime": "2023-07-21 20:17:06",
    "paid_datetime": "2023-07-21 20:18:13",
    "cancelled_datetime": null,
    "cancelled_reason": null,
    "currency": "KRW",
    "quantity": 1,
    "additionalInfo": null,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "purchase_bypass_info": "eyJ0eXBlIjoicGFpZCIsIm1hcmtldF9pZCI6IjE1Iiwib3JkZXJfaWQiOi..."
}

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

{
    "type": "cancelled",
    "market_id": "15",
    "order_id": "H2168993822440686730",
    "market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
    "vid": "20000011337",
    "uid": "67200717",
    "vid_type": "v4",
    "server_id": "kr",
    "appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
    "amount": "1200",
    "started_datetime": "2023-07-21 20:17:06",
    "paid_datetime": "2023-07-21 20:18:13",
    "cancelled_datetime": "2023-07-21 20:21:44",
    "cancelled_reason": "테스트 결제 취소",
    "currency": "KRW",
    "quantity": 1,    
    "additionalInfo": null,
    "hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
    "purchase_bypass_info": "eyJ0eXBlIjoiY2FuY2VsbGVkIiwibWFya2V0X2lkIjoiMT..."
}