웹 PG 결제
웹 PG 결제 API는 Windows 앱 개발 시 Hive SDK 빌링을 사용하지는 않지만, 웹사이트에서 PG 결제를 구현하기 원할 때 사용하는 API입니다. 웹 PG 결제 API는 앱에서 PG 결제를 구현하는 API와는 다릅니다.
Note
앱에서 PG 결제를 구현하려면 Hive SDK 빌링과 일반 PG 결제 API를 사용해야 합니다.
상품 목록 조회¶
상품 정보를 가져옵니다. 앱에서 상품 목록을 구현하는 데 사용합니다.
Request URL¶
Environment | URL |
---|---|
상용 URL | https://store.withhive.com/external/api/product |
샌드박스 URL | https://sandbox-store.withhive.com/external/api/product |
HTTP Method | POST |
Content-Type | text/html; charset=utf-8 |
Data Format | JSON |
Authorization | Bearer (토큰) |
Bearer 토큰은 Hive 콘솔의 앱센터 > 프로젝트 관리 > 게임사 게임 선택 > 게임 상세 > 기본정보 에서 Hive 인증키에 해당합니다.
Request parameters¶
Field | Type | Required | Description |
---|---|---|---|
api | String | O | api 구분값 (`product` 고정값 사용) |
market_id | String | O | Hive 마켓 ID (PG 결제: `15` 고정값 사용) |
appid | String | O | Hive Appid |
hive_country | String | O | 국가 코드(ISO 3166-1 두자리) |
game_language | String | O | 언어(ISO 639-1 두자리) |
vid | String | O | Hive 계정 정보(Player ID) |
vid_type | String | O | 계정 타입(신규 게임의 경우 v4) |
market_pid_type | String | O | 상품 타입 (소모성: consumable) |
Response elements¶
Field | Type | Required | Description |
---|---|---|---|
result | Integer | O | 응답 코드 (0이 성공 그 외는 에러) |
result_msg | String | O | 응답 메시지 |
product_list | Object | O | 상품 정보 리스트 |
product_list > market_pid | String | O | 상품 PID |
product_list > price | Int | O | 상품 가격 (숫자값) |
product_list > currency | String | O | 상품 가격 통화 |
product_list > display_price | String | O | 상품 가격 (통화 기호 포함) |
product_list > title | String | O | 상품명 |
product_list > description | String | O | 상품 설명 |
product_list > product_type | String | O | 상품 구분 (소모성: consumable) |
update_date | String | O | 상품 PID 정보 최종 업데이트 일시 |
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¶
Environment | URL |
---|---|
상용 URL | https://store.withhive.com/external/api/order |
샌드박스 URL | https://sandbox-store.withhive.com/external/api/order |
HTTP Method | POST |
Content-Type | text/html; charset=utf-8 |
Data Format | JSON |
Authorization | Bearer (토큰) |
Bearer 토큰은 Hive 콘솔의 앱센터 > 프로젝트 관리 > 게임사 게임 선택 > 게임 상세 > 기본정보 에서 Hive 인증키에 해당합니다.
Request parameters¶
Field | Type | Required | Description |
---|---|---|---|
market_id | String | O | Hive 마켓 ID |
appid | String | O | Hive Appid |
hive_country | String | O | 국가 코드(ISO 3166-1 두자리) |
game_language | String | O | 언어(ISO 639-1 두자리) |
vid | String | O | Hive 계정정보(Player ID) |
vid_type | String | O | 계정 타입(신규 게임의 경우 v4) |
market_pid | String | O | 상품 PID |
server_id | String | O | 서버 아이디 |
os | String | O | Window: W, MAC: M, Android: A |
quantity | Integer | X | 구매 수량 (미 전송시 기본 값 1) |
iap_payload | String | X | 앱 개발사에서 정의한 구매 메타 정보 |
fixed_currency | String | X | 결제 수단 노출 통화(ISO 4217 세자리) * 필수 값이 아니며, 요청 파라메터에 fixed_currency 항목이 없으면 hive_country 기준으로 결제 수단이 노출 되지만 fixed_currency 항목을 추가하면 fixed_currency 통화 기준으로 결제 수단이 노출됨 |
refund_idx | Integer | X | 환불 유저 재결제 목록 IDX * 환불 유저 재결제 요청 시에만 필요 |
is_repayment | Integer | X | 환불 유저 재결제 여부 (0:일반결제,1:환불유저재결제) * 환불 유저 재결제 요청 시에만 필요 |
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) |
┕ started_datetime_ms | Number | M | 결제를 시작한 시간 (Unix TimeStamp Milliseconds) |
┕ paid_datetime_ms | Number | M | 결제를 완료한 시간 (Unix TimeStamp Milliseconds) |
┕ hiveiap_receipt | String | M | 결제 정보 암호화 HASH |
┕ purchase_bypass_info | String | M | 영수증 검증 요청에 필요한 필수 정보 |
┕ iap_payload | 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...",
"started_datetime_ms": 1647925429000,
"paid_datetime_ms": 1647925479000,
"iap_payload": 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¶
결제 결과 알림 서비스¶
결제 결과 알림 서비스는 결제 완료 또는 결제 취소가 발생하는 즉시 해당 결과를 게임 서버로 전송합니다. 이 API는 결제 완료 내역 조회와 동일하게 purchase_bypass_info
값을 전달하므로, 게임은 이 값을 사용해 영수증을 검증한 후 유저에게 상품을 지급할 수 있습니다. 결제 결과 전송 정보에서 type
이 paid일 경우에만 영수증 검증과 상품 지급을 진행해야 합니다.
Note
이 API를 사용하려면 먼저 Hive 콘솔에서 사용할 PG사를 설정해야 합니다. 영수증 검증과 상품 지급을 위해서는 이 API 또는 결제 완료 내역 조회 API 둘 중 하나만 사용하는 것을 권장합니다.
결제 결과 전송 기본 사항¶
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 | String | M | 구매한 유저의 PlayerID, v1 인증의 경우 VID |
vid_type | String | O | SDK 버전에 따른 vid 유형 값(기본 v4) |
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) |
cancelled_datetime | Datetime | O | 결제가 취소 또는 환불된 시간 (Y-m-d H:i:s) |
started_datetime_ms | Number | M | 결제를 시작한 시간 (Unix TimeStamp Milliseconds) |
paid_datetime_ms | Number | M | 결제를 완료한 시간 (Unix TimeStamp Milliseconds) |
cancelled_datetime_ms | Number | O | 결제가 취소 또는 환불된 시간 (Unix TimeStamp Milliseconds) |
cancelled_reason | String | O | 결제가 취소 또는 환불된 사유 |
hiveiap_receipt | String | M | 결제 정보 암호화 HASH |
purchase_bypass_info | String | M | 영수증 검증 요청에 필요한 필수 정보 |
iap_payload | 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,
"hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
"started_datetime_ms": 1689938226000,
"paid_datetime_ms": 1689938293000,
"cancelled_datetime_ms": null,
"iap_payload": null,
"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,
"hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
"started_datetime_ms": 1689938226000,
"paid_datetime_ms": 1689938293000,
"cancelled_datetime_ms": 1689938504000,
"iap_payload": null,
"purchase_bypass_info": "eyJ0eXBlIjoiY2FuY2VsbGVkIiwibWFya2V0X2lkIjoiMT..."
}
환불 유저 재결제 대상 환불 내역 조회 API¶
환불한 유저가 재결제가 필요한 경우, 환불 내역을 조회합니다.
자체 구현한 웹상점에서 환불 유저 재결제 기능을 활성화했다면, '환불 유저 재결제 대상 환불 내역 조회' API 응답 값을 이용하여 환불 유저 대상 재결제 안내 팝업 UI를 구현해야 합니다.
'환불 유저 재결제 대상 환불 내역 조회' API 사용 시, 아래 사항을 숙지하세요.
- PlayerID 조회 API의 응답 항목 중
is_refund
가 true일 경우에만 사용할 수 있습니다. - 재결제 건에 대한 결제 요청 시 요청 파라메터 json 항목에
refund_idx(Integer)
,is_repayment(Integer)
를 필수로 추가해야 합니다.
Request URL¶
Environment | URL |
---|---|
상용 URL | https://store.withhive.com/external/api/refund_info |
샌드박스 URL | https://sandbox-store.withhive.com/external/api/refund_info |
HTTP Method | POST |
Content-Type | text/html; charset=utf-8 |
Data Format | JSON |
Authorization | Bearer (토큰) |
Bearer 토큰은 Hive 콘솔의 앱센터 > 프로젝트 관리 > 게임사 게임 선택 > 게임 상세 > 기본정보 에서 Hive 인증키에 해당합니다.
Request parameters¶
Field | Type | Required | Description |
---|---|---|---|
appid | String | O | Hive Appid |
vid_type | String | O | 계정 타입(신규 게임의 경우 "v4") |
vid | String | O | Hive 계정정보(Player ID) |
game_language | String | O | 언어(ISO 639-1 두자리) |
device | String | X | PC, Mobile 구분 (pc, mobile) * device 항목이 없을 경우 mobile로 세팅되어 응답 |
Response elements¶
Field | Type | Required | Description |
---|---|---|---|
result | Integer | O | 응답 코드 (0이 성공 그 외는 에러) |
result_msg | String | O | 응답 메시지 |
guide_title | String | O | 가이드 제목 |
guide_content | String | O | 가이드 내용 |
customer_site | Object | O | 고객센터 주소 |
customer_site > pc | String | O | PC 고객센터 주소 |
customer_site > mobile | String | O | Mobile 고객센터 주소 |
refund_list | Array > Object | O | 환불 재결제 목록 |
refund_list > refund_idx | Integer | X | 재결제 INDEX ID |
refund_list > market_id | Integer | X | Hive 마켓 ID |
refund_list > market_pid | String | X | 상품 PID |
refund_list > refund_time | String | X | 환불 일시 |
refund_list > refund_time_ms | Integer | X | 환불 일시 (Unix TimeStamp Milliseconds) |
refund_list > quantity | Integer | X | 상품 구매 수량 |
Request example¶
curl -L -v \
-d '{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","vid_type":"v4","vid":"20000015900","game_language":"ko","device":"pc"}' \
-H "Content-Type: text/html" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
https://sandbox-store.withhive.com/external/api/refund_info
Response example¶
{
"result": 0,
"result_msg": "success",
"guide_title": "환불 상품 재결제 안내",
"guide_content": "고객님의 계정은 게임 서비스 약관 및 운영 정책 위반 행위(결제시스템 악용)가 확인되어,
게임 이용이 제한되었습니다.\n\n알 수없는 이유로 결제가 취소되었거나, 혹은 비정상적인 절차로 환불된 상품의 경우, 동일 상품 재결제 후 게임 이용이 가능합니다.\n\n 현재 접속한 단말OS의 마켓 상품만 재결제가 가능하오니, 다른 마켓은 해당 앱으로 접속하여 재결제 부탁드립니다.
스팀 환불 내역에 대한 재결제는 PC에서 진행하세요. 모든 마켓의 취소/환불 상품의 재결제가 완료되어야 게임 이용이 가능합니다.\n\n일부 마켓에서 한 상품을 여러 수량으로 한 번에 구매 후 환불한 경우,
동일한 수량으로 재결제 해야 합니다. 만약 환불한 수량과 재결제한 수량이 일치하지 않으면 해당 재결제 건은 자동 취소됩니다.
취소되는 시점은 마켓에 따라 상이하며 수일이 걸릴 수 있습니다.\n\n 재결제 도중 오류로 인하여 결제 실패한 경우, 현재 계정으로 다시 게임을 재실행해주세요. 디바이스를 변경하여 동일한 마켓계정이면서 다른 게임 계정으로 로그인하시면 결제가 정상적으로 완료되지 않을 수 있습니다.\n\n결제 불가상품을 비롯한 그밖의 문의사항은 고객센터로 접수 부탁드립니다.\n\n* 환불 시간은 UTC+9 기준입니다.",
"customer_site": {
"pc": "https://sandbox-customer.withhive.com/com2us/faq/game/539",
"mobile": "https://sandbox-customer-m.withhive.com/com2us/faq/game/539"
},
"refund_list": [
{
"refund_idx": 20850,
"market_id": 1,
"market_pid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01",
"refund_time": "2023.02.02 15:47 (UTC+9)",
"refund_time_ms": 1675320475000,
"quantity": 1
}
]
}