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. For games that have a separate game server and use STOVE Billing System must have this feature integrated.
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
C++
복사
Where to register your Partners URL
Please contact STOVE Onboarding Manager
Request
Header
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 | Description |
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 STOVE 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: Cancelbr>
-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"
}
}
C++
복사
Response
{
"code": 0,
"message": "OK"
}
C++
복사
Return Code
HTTP Status code | response_code | response_message | Description |
200 | 0 | OK | Success |
500 | 500 | Internal Server Error | Server internal errors |