# 결제 완료 알림

# 소개

이 문서는 유저 결제 완료 후 STOVE 빌링 미들웨어가 게임서버로 전달하는 아이템지급 요청에 대한 데이터 처리 방법을 안내 합니다.
본 기능은 스토브 빌링 시스템 사용시 게임 서버에서 필수로 구현해야 합니다.
호출 방식은 RESTful API 형태로 호출되며, 전달되는 정보는 아래 API 기본 정보를 참고해 주세요.

유저 결제가 완료되면 STOVE 빌링 미들웨어는 파트너스에 등록 된 게임 서버 URL 주소로 `아이템 지급에 필요한 상품정보 와 게임 아이템 정보(Json)`를 전달 합니다.
게임 서버는 해당 지급 정보를 수신 -> 유저에게 지급 처리 -> 빌링 미들웨어 지급 결과를 응답 해줘야 합니다.
  - 상품 구매 시 지급 재화/아이템 구성 중 아이템이 있을 경우 `결제 완료 알림 API`로 결제 완료 된 상품 정보와 지급해야 할 게임 아이템 정보를 전달합니다.
  - 모바일의 경우) OOAP 상품 서비스 시 [파트너스 > MobileBilling > 빌링 정보 연동 > OOAP 지급 방식] 설정에 따라 게임에서 OOAP 상품을 자유롭게 지급할 수 있도록 구매 완료 된 OOAP 상품 정보를 전달합니다.
  - 모바일의 경우) 구독 상품 서비스 시 유저별 구독 상태가 변경될 때( 만료일 변경 or 구독 갱신 등) 변경된 상태 정보를 전달합니다. (현재 구독 상품 서비스 기능은 현재 미 제공 상태임)

  주의) API로 전달한 TID(스토브 빌링 결제 주문번호)는 게임 서버에서 저장 후 관리하여 중복지급이나 미지급이 발생되지 않도록 해야 합니다.

# 기본정보

POST 파트너스 통해 URL 등록
Host:
   https://I-api.onstove.com (LIVE)    
   https://I-api.gate8.com (SB)
Content-Type: application/json

1
2
3
4
5

# 파트너스 URL 등록 위치

파트너스 > Billing > 빌링 설정 > 빌링 연동 정보 관리 > '결제 완료 알림 URL* (게임 월드 별 Noti URL)' 항목 사전 등록 필요함. [바로가기](https://partners.gate8.com/main#menu_no=743&menu_id=BC00000003332&menu_index=5-2-0&menu_depth=3&menu_gnbno=6&menu_topnav=true&menu_hash=4584)

# Request

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	게임코드 (STOVE에서 발급 - 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	-	월드(서버) 구분
guid	string(50)	Y	-	-	스토브 회원 GUID(게임별 유저 유니크 아이디).GUID가 없는 게임(싱글플레이 게임)을 제외하고 필수
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	해당 금액의 통화
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(모바일 구독상품)

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"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# Response

{  
    "code": 0,
    "message": "OK"
}

1
2
3
4

# Return Code

HTTP Status code	response_code	response_message	Description
200	0	OK	성공
500	500	Internal Server Error	서버 내부 오류

← 결제 유효성 체크 웹(Web) 인증 →

# 결제 완료 알림

# 소개

# 기본정보

# 파트너스 URL 등록 위치

# Request

# Header

# Path Variable

# Body

# data(온라인 일반상품)

# Data(모바일 일반상품 / OOAP 상품)

# supply_items

# Data(모바일 구독상품)

# Response

# Body

# Sample

# Request

# Response

# Return Code