# Payment completion notification

# Introduction

This document describes how the STOVE billing middleware handles data for item payment requests that are forwarded to the game server after a user has made a payment.
This feature must be implemented on the game server when using the STOVE billing system.
The call is made in the form of a RESTful API, and the information passed is described in the API basics below.

When the user payment is completed, the STOVE billing middleware delivers `product information and game item information (Json) required for item payment` to the game server URL address registered with the partner.
The game server needs to receive the payment information -> process the payment to the user -> respond to the billing middleware payment result.
  - When purchasing a product, if there are items in the payment goods/items configuration, pass the completed product information and game item information to the `Payment Completion Notification API`.
  - For mobile) When servicing OOAP products, pass the completed OOAP product information so that you can freely pay OOAP products in the game according to the [Partners > MobileBilling > Integrate billing information > OOAP payment method] setting.
  - In the case of mobile) When the subscription status of each user changes during the subscription service (such as expiration date change or subscription renewal), the changed status information is passed. (Currently, the subscription service feature is not currently available.)

  Caution) The TID (stove billing payment order number) passed to the API must be stored and managed by the game server to prevent double payment or non-payment.

# Basic information

POST Registering URLs through partners
Host:
   https://I-api.onstove.com (LIVE)    
   https://I-api.gate8.com (SB)
Content-Type: application/json

1
2
3
4
5

# Where to register your Partners URL

Partners > Billing > Billing settings > Manage billing integration information > 'Payment completion notification URL* (Noti URL per game world)' item requires pre-registration. [More].(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 caller information

# Path Variable

Name	Type	Required	Default Value	Example	Description
service_id	String	Y	-	STOVE_QA	Game code (issued by STOVE - game_id)

# Body

Name	Type	Required	Default Value	Example
bill_platform_type	string(16)	Y	-	Payment platform type (required when checking validity) -MOBILE: Mobile billing -ONLINE: Online billing -SHOP: Store
noti_type	string(32)	Y	-	Notification Category -ONLINE_PURCHASE : Purchase of online general products -IAP_PURCHASE : Purchase of mobile general products -IAP_SUBSCRIPT : Purchase of mobile subscription products -IAP_OOAP : Purchase of mobile OOAP products
world_id	string(30)	N	-	World (server) classification
member_no	long	Y	-	Membership number
character_no	string(20)	N	-	Unique key issued for each game character (issued by STOVE)
txn_time	long	Y	-	Payment time (Unix Timestamp UTC-0)
data	json object	Y	-	detailed data

# data(Online general merchandise)

Name	Type	Required	Default Value	Example	Description
tid	string(20)	Y	-	T202202103125	Order number issued by Stoves Billing
product_id	string(20)	Y	-	p1002	Product code registered on the Stove platform
product_currency	string(3)	Y	-	KRW, USD	Currency of the amount
product_price	decimal	Y	-	1100, 0.99	Transaction amount
inservice_item_id	string(30)	Y	-	cp7892	In-game item ID
service_order_id	string(20)	N	-	Game payload passed to the payment server when requesting payment (currently unsupported spec)

# Data(Mobile General Products / OOAP Products)

Name	Type	Required	Default Value	Example	Description
tid	string(20)	Y	-	-	Order number issued by Stove Billing
pay_type	string	Y	-	-	Payment type -General: INAPP -OOAP -OOAP_PROMO: Promotion code payment -OOAP_POINT: Point payment
market_code	string(20)	Y	-	APPLE_APP_STORE, GOOGLE_PLAY, STOVE_ONLINE	Market Code
market_product_id	string(50)	Y	-	-	Code of product registered in the market
product_id	string(20)	Y	-	-	Product code registered on the stove platform
product_currency	string(3)	Y	-	KRW, USD	Currency of the amount
product_price	decimal	Y	-	1100, 0.99	Product amount registered on the stove platform (based on the set tier)
product_price_tier	Integer	Y	-	1	Tier number set for the product -Required for mobile market payments
inservice_item_id	string(30)	N	-	-	In-game item ID
service_order_id	string(20)	N	-	-	Game payload delivered to the payment (IAP) server when requesting payment
supply_items	Array	N	-	-	Item information to be paid when purchasing a product (excluding product information)

# supply_items

Name	Type	Required	Default Value	Example	Description
service_item_code	string(30)	Y	-	-	Item code -Item code provided in the game
total_amount	String	Y	-	-	Quantity paid -at least 1
item_desc	string(100)	N	-	-	Additional information/description of item -Additional information/description of item registered with partner

# Data(Mobile subscriptions)

Name	Type	Required	Default Value	Example	Description
tid	string(20)	Y	-	-	Order number issued by Stove Billing -Order number consisting of 19 digits (changed when subscription is renewed)
original_tid	string(20)	Y	-	-	Stove order number issued upon first payment of subscription product -Order number consisting of 19 digits -First payment of subscription product: tid = original_tid -Automatic renewal of subscription product: tid != original_tid
pay_type	string	Y	-	SUBSCRIPTION	Payment category
market_code	string(20)	Y	-	APPLE_APP_STORE, GOOGLE_PLAY	Market Code
market_product_id	string(50)	Y	-	-	Code of product registered in the market
product_id	string(30)	Y	-	-	Product code registered on the stove platform
product_currency	string(3)	Y	-	KRW, USD	Currency of the amount
product_price	float	Y	-	1100, 0.99	Product amount registered on the stove platform (based on the set tier)
product_price_tier	Integer	Y	-	1	Tier number set for the product
inservice_item_id	string(30)	N	-	-	Registered value if there is a separate in-game item code that matches the IAP product
subs_status_code	string	Y	-	-	Subscription status code -PURCHASE: Subscription first payment -RENEWED: Subscription renewal -PAUSED: Pause -GRACE: Grace period -CANCELED: Cancel br>-REVOKE : Refund -EXPIRED : Subscription expiration -CHANGED : Status change -NCHANGE : Next subscription status change -FAILED : Auto-renewal failed - UNKNOW: Unknown code (may occur briefly when a new code is added to the market)
expire_time	long	Y	-	-	Expiration Date (UTC)
market_subscript_status	string	Y	-	Classification of subscription product status delivered by market -The status code delivered by market is not the same, but is provided for reference only

# Response

# Body

Name	Type	Required	Default Value	Example	Description
code	Integer	Y	-	0	Response Code
message	String	Y	-	OK	Response message

# Sample

# Request

curl --location --request POST'Registering URLs through partners' \
--header 'caller-id: {{caller-id}}'

Online General Merchandise
{
    "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"
}
Mobile General Products / OOAP Products
{
    "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": ""
               }]
        }
}
Mobile subscriptions
{
    "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	Success
500	500	Internal Server Error	Server internal errors

← Check payment validity Studio Quick Guide →

# Payment completion notification

# Introduction

# Basic information

# Where to register your Partners URL

# Request

# Header

# Path Variable

# Body

# data(Online general merchandise)

# Data(Mobile General Products / OOAP Products)

# supply_items

# Data(Mobile subscriptions)

# Response

# Body

# Sample

# Request

# Response

# Return Code