Introduction
이 문서는 유저 결제 완료 후 STOVE 빌링 미들웨어가 게임서버로 전달하는 아이템지급 요청에 대한 데이터 처리 방법을 안내 합니다. 본 기능은 스토브 빌링 시스템 사용시 게임 서버에서 필수로 구현해야 합니다. 호출 방식은 RESTful API 형태로 호출되며, 전달되는 정보는 아래 API 기본 정보를 참고해 주세요.
유저 결제가 완료되면 STOVE 빌링 미들웨어는 파트너스에 등록 된 게임 서버 URL 주소로 `아이템 지급에 필요한 상품정보 와 게임 아이템 정보(Json)`를 전달 합니다.
게임 서버는 해당 지급 정보를 수신 -> 유저에게 지급 처리 -> 빌링 미들웨어 지급 결과를 응답 해줘야 합니다.
•
상품 구매 시 지급 재화/아이템 구성 중 아이템이 있을 경우 `결제 완료 알림 API`로 결제 완료 된 상품 정보와 지급해야 할 게임 아이템 정보를 전달합니다.
•
모바일의 경우) OOAP 상품 서비스 시 [파트너스 > MobileBilling > 빌링 정보 연동 > OOAP 지급 방식] 설정에 따라 게임에서 OOAP 상품을 자유롭게 지급할 수 있도록 구매 완료 된 OOAP 상품 정보를 전달합니다.
•
모바일의 경우) 구독 상품 서비스 시 유저별 구독 상태가 변경될 때( 만료일 변경 or 구독 갱신 등) 변경된 상태 정보를 전달합니다. (현재 구독 상품 서비스 기능은 현재 미 제공 상태임)
주의) API로 전달한 TID(스토브 빌링 결제 주문번호)는 게임 서버에서 저장 후 관리하여 중복지급이나 미지급이 발생되지 않도록 해야 합니다.
#Basic information
POST 파트너스 통해 URL 등록
Host:
https://I-api.onstove.com (LIVE)
https://I-api.gate8.com (SB)
Content-Type: application/json
C++
복사
파트너스 URL 등록 위치
스토브 담당자에게 문의 부탁드립니다.
Request
Header
Name | Type | Required | Default Value | Example | Description |
caller-id | String | Y | - | clientapp | API 호출자 정보 |
Path Variable
Name | Type | Required | Default Value | Example | Description |
service_id | String | Y | - | STOVE_QA | Game_id |
Body
Name | Type | Required | Default Value | Example | Description |
bill_platform_type | string(16) | Y | - | 결제한 플랙폼 타입(유효성 체크 시 필요)
-MOBILE : 모바일 빌링
-ONLINE : 온라인 빌링
-SHOP: 상점 | |
noti_type | string(32) | Y | - | notification 구분
-ONLINE_PURCHASE : 온라인일반상품 구매
-IAP_PURCHASE : 모바일 일반상품 구매
-IAP_SUBSCRIPT : 모바일 구독상품 구매
-IAP_OOAP : 모바일 OOAP 상품 구매 | |
world_id | string(30) | N | - | 월드(서버) 구분 | |
member_no | long | Y | - | 회원 번호 | |
character_no | string(20) | N | - | 게임 캐릭터 별로 발급되는 키값(STOVE에서 발급) | |
txn_time | long | Y | - | 결제 시각(Unix Timestamp UTC-0) | |
data | json object | Y | - | 상세 데이터 |
Data(온라인 일반 상품)
Name | Type | Required | Default Value | Example | Description |
tid | string(20) | Y | - | T202202103125 | 스토브 빌링에서 발급한 주문번호 |
product_id | string(20) | Y | - | p1002 | 스토브 플랫폼에 등록한 상품 코드 |
product_currency | string(3) | Y | - | KRW, USD | Currency of the amount해당 금액의 통화 |
product_price | decimal | Y | - | 1100, 0.99 | 거래 금액 |
inservice_item_id | string(30) | Y | - | cp7892 | 게임내 아이템ID |
service_order_id | string(20) | N | - | 결제요청시 결제 서버에 전달한 게임 payload(현재 미지원 Spec) |
Data(모바일 일반상품 / OOAP 상품)
Name | Type | Required | Default Value | Example | Description |
tid | string(20) | Y | - | - | 스토브 빌링에서 발급한 주문번호 |
pay_type | string | Y | - | - | 결제 구분
-일반 : INAPP
-OOAP
-OOAP_PROMO : 프로모션 코드 결제
-OOAP_POINT : 포인트 결제 |
market_code | string(20) | Y | - | APPLE_APP_STORE, GOOGLE_PLAY, STOVE_ONLINE | 마켓 코드 |
market_product_id | string(50) | Y | - | - | 마켓에 등록된 상품의 코드 |
product_id | string(20) | Y | - | - | 스토브 플랫폼에 등록한 상품 코드 |
product_currency | string(3) | Y | - | KRW, USD | 해당 금액의 통화 |
product_price | decimal | Y | - | 1100, 0.99 | 스토브 플랫폼에 등록한 상품 금액(설정한 tier기준) |
product_price_tier | Integer | Y | - | 1 | 해당 상품에 설정된 tier번호
-모바일 마켓 결제의 경우 필수 |
inservice_item_id | string(30) | N | - | - | 게임 내 아이템ID |
service_order_id | string(20) | N | - | - | 결제요청시 결제(IAP) 서버에 전달한 게임 payload |
supply_items | Array | N | - | - | 상품구매시 지급해야할 아이템 정보(재화 정보 제외) |
supply_items
Name | Type | Required | Default Value | Example | Description |
service_item_code | string(30) | Y | - | - | 아이템 코드
-게임내에 제공하는 아이템 코드 |
total_amount | String | Y | - | - | 지급 수량
-최소 1이상 |
item_desc | string(100) | N | - | - | 아이템 부가정보/설명
-파트너스에 등록한 아이템 부가정보/설명 |
Data(Mobile subscriptions)
Name | Type | Required | Default Value | Example | Description |
tid | string(20) | Y | - | - | 스토브 빌링에서 발급한 주문번호
-19자리 숫자로 이루어진 주문번호( 구독 갱신시 변경됨 |
original_tid | string(20) | Y | - | - | 구독상품 첫결제 시 발급된 스토브 주문번호
-19자리 숫자로 이루어진 주문번호
-구독상품 첫결제 : tid = original_tid
-구독상품 자동개신 : tid != original_tid |
pay_type | string | Y | - | SUBSCRIPTION | 결제 구분 |
market_code | string(20) | Y | - | APPLE_APP_STORE, GOOGLE_PLAY | 마켓 코드 |
market_product_id | string(50) | Y | - | - | 마켓에 등록된 상품의 코드 |
product_id | string(30) | Y | - | - | 스토브 플랫폼에 등록한 상품 코드 |
product_currency | string(3) | Y | - | KRW, USD | 해당 금액의 통화 |
product_price | float | Y | - | 1100, 0.99 | 스토브 플랫폼에 등록한 상품 금액(설정한 tier기준) |
product_price_tier | Integer | Y | - | 1 | 해당 상품에 설정된 tier번호 |
inservice_item_id | string(30) | N | - | - | IAP상품과 매칭되는 게임내 아이템코드가 따로 있을 경우 등록된 값 |
subs_status_code | string | Y | - | - | 구독상태 코드
-PURCHASE : 구독 첫결제
-RENEWED : 구독 갱신
-PAUSED : 일시정지
-GRACE : 유예기간
-CANCELED : 취소
-REVOKE : 환불
-EXPIRED : 구독 만료
-CHANGED : 상태변경
-NCHANGE : 다음 구독상태 변경
-FAILED : 자동갱신 실패
-UNKNOW : 알수없는 코드( 마켓에 신규 코드가 추가되었을 경우 잠시 발생가능 ) |
expire_time | long | Y | - | - | 만료일(UTC기준) |
market_subscript_status | string | Y | - | 마켓에서 전달한 구독상품 상태 구분
-마켓별로 전달되는 상태 코드가 동일하지 않지만, 참고용으로 전달 |
Response
Body
Name | Type | Required | Default Value | Example | Description |
code | Integer | Y | - | 0 | 응답 코드 |
message | String | Y | - | OK | 응답 메시지 |
Sample
Request
curl --location --request POST'파트너스 통해 URL 등록' \
--header 'caller-id: {{caller-id}}'
온라인 일반상품
{
"bill_platform_type": "ONLINE",
"noti_type": "ONLINE_PURCHASE",
"member_no": "265265",
"txn_time" : 1644807685000,
"data": {
"tid": "1909091033503333452",
"product_id": "test_1",
"product_price": 5000.0,
"product_currency": "KRW",
"inservice_item_id": "test_1",
"service_order_id": "testtest_1234"
}
모바일 일반상품 / OOAP 상품
{
"bill_platform_type": "MOBILE",
"noti_type": "IAP_PURCHASE",
"character_no": "67891",
"member_no": "67891",
"world_id": "world_1",
"txn_time" : 1644807685000,
"data": {
"tid": "1909091033503333452",
"pay_type": "INAPP",
"market_code": "GOOGLE_PLAY",
"market_product_id": "google_test_1",
"product_id": "test_1",
"product_price": 5000.0,
"product_currency": "KRW",
"product_tier": 1,
"inservice_item_id": "test_1",
"service_order_id": "testtest_1234",
"supply_items": [
{
"service_item_code": "potion_h",
"total_amount": 2,
"item_desc": ""
}]
}
}
모바일 구독상품
{
"bill_platform_type": "MOBILE",
"noti_type" : "IAP_SUBSCRIPT",
"character_no" : "67891"
"member_no" : "67891",
"world_id" : "world_1",
"txn_time" : 1644807685000,
"data":{
"tid": "1909091033503333452",
"original_tid": "o1909091033503333452",
"pay_type":"SUBSCRIPTION",
"market_code":"GOOGLE_PLAY",
"market_product_id":"google_test_1",
"product_id": "test_1",
"product_price":5000.0,
"product_currency":"KRW",
"product_tier" : 1,
"inservice_item_id":"test_1",
"subs_status_code" : "PURCHASE",
"expire_time" : 2478329479,
"market_subscript_status":"7"
}
}
Plain Text
복사
Response
{
"code": 0,
"message": "OK"
}
Plain Text
복사
Return Code
HTTP Status code | response_code | response_message | Description |
200 | 0 | OK | 성공 |
500 | 500 | Internal Server Error | 서버 내부 오류 |