Skip to content
Stove
Cập nhật lần cuối

Are you curious about the actual implementation flow?

Usage Scenario / Purchasing in-game

Coupon

Understanding


By integrating the Stove platform's coupon service, you can issue coupons via Stove Partners to provide rewards such as items to users in-game or on the web.
Coupons are used to increase user retention through pre-registration, collaborations, event rewards, marketing acquisition/conversion tracking, and manual CS rewards.

Coupon Popup Support Scope and Exposure Location
ㆍ SDK Popup Support: Mobile games, multi-platform (PC+mobile) games (including PC builds)
ㆍ iOS/PC-only games: Register via the Stove website coupon box or game homepage instead of the SDK popup
ㆍ Exposure Location: Designated by the CP (developer) according to the game UX (e.g., Main Lobby > Settings > Register Coupon)

Coupon Types and Rewards

You can choose the right coupon for your situation by reviewing the types of coupons and reward configurations.

Which coupon should you use?

First, try selecting the coupon type that fits your situation.


Coupon Type Selection Guide

Do users enter the code themselves?

├─ Yes · 1 unique code per person (Pre-registration, CS, personal events) → General Coupon

├─ Yes · 1 public code for multiple people to use (SNS, collaborations) → Representative (Public) Coupon

├─ Yes · Only pre-registered targets can enter/use the code (Beta, tier-specific) → Target-Specific Coupon

├─ No · Issued directly to a specific user account (VIP, CS, attendance) → Account-Issued Coupon

└─ No · Issued directly to the account of the user who downloaded it (currently mainly used in the store) → Download Coupon

Coupon Type

The issuance method and the user's experience of receiving the coupon vary depending on the coupon type.

Coupon Type Category Features Main Usage
General Coupon 1 : 1 One code used by one person, manual code entry Pre-registration, personal events, CS rewards
Representative (Public) Coupon 1 : N One code used by multiple people, public code entry Collaborations, SNS, seasonal events
Account-Issued Coupon Automatic issuance Automatically added to the coupon box without entry VIP, errors, manual CS rewards
Target-Specific Coupon Designated targets only Only registered targets can use it (target verification) Beta testers, tier-specific events
Download Coupon Store Integration Loaded into the coupon box after downloading from the store (additional integration required)
※ If the CP directly builds and integrates the download coupon box, it can also be used in-game, but currently, it is mainly used in the "Store".
Encourage Store Visits
What should we give as a reward? (Coupon Attributes)

Coupon Typeis about "who to give it to and how to distribute it," while coupon Attributeis about "what to give."
When issuing, first determine the type, then set the attribute (reward)in that order.


Reward Types What do you give? Features / Constraints
Item Coupon In-game items/currency Distributed based on member number or character number
Discount Coupon Discount upon payment (fixed amount/rate) Used for both in-game and store
※ In-game discount coupons are used at the payment window
※ Shopping cart/bundle discount options are store-exclusive
Game Pass Coupon A pass that allows free use of store games Can only be used in the store
Commonly Used Combinations (Type × Reward)

"When to use what" — These are combinations actually used frequently.

Recommended Combinations

· Distributing items via SNS/collaboration → Representative (Public) Coupon + Item

· Individual item distribution / Pre-registration / CS compensation → General Coupon + Item

· Direct item distribution to specific users (VIP/error compensation) → Account-issued Coupon + Item

· In-game payment discount event → General or Representative (Public) Coupon + Discount (Users use it at the payment window)

· Providing game passes to creators/promoters (trial offer) → Account-issued Coupon + Game Pass

Screen Examples by Setting

Depending on the coupon type and detailed settings, the screen and experience the user sees in-game will vary.

Setting Combination User Screen
General Coupon + Use Prefix First 4 digits fixed (e.g., FREEXXXXXX) → Suitable for events/collaborations with a brand coupon feel
Representative Coupon + Automatic Random Number Generation Public code (e.g., 2350DWG06Z0009S5) entered in-game, first-come-first-served/period limits can be set
Account-issued Coupon (No entry required) Automatically loaded into the coupon box without entry, checked via notifications/coupon box

Coupon Issuance Flow

This is the overall flow from issuing a coupon to it being delivered to the user.

Step 1. Set Coupon Information

In Partners [Publishing Center > Manage Basic Billing Settings > Set Coupon Information], enter the coupon type, reward, representative image, etc.

ℹ️ This step only needs to be set once initially.
Once set, you don't need to do it again for each subsequent issuance, and you only need to modify it when you want to change settings like type or reward. Actual coupon issuance is repeated from Step 2.

Coupon Information Setting Guide
ㆍ Set the coupon type/attribute to use (Required before issuance)
ㆍ Use Stove Coupon Box Y → Game name displayed in My Info Coupon Box (ascending order by group)
ㆍ Game pass attribute is store-exclusive
ㆍ Representative image in information settings takes priority over issuance image
ㆍ Coupon maintenance settings available when selecting Stove as the game name


Step 2. Issue Coupon

In Partners [Publishing Center > Manage Basic Billing Settings > Issue Coupon], set basic information such as coupon name, type, and attributes.

Coupon Information (Coupon Name, Description, Reward Text, Precautions)
ㆍ Multilingual support, enter in-game display text (item reward text)
ㆍ Copy Coupon Information: Entering an existing coupon ID automatically loads most issuance information


Coupon Types and Properties
ㆍ The default usage country is set to 'All' (configure separately if restricted to specific countries)
ㆍ Types and properties are loaded from the information settings menu (Download coupons are store-exclusive; properties are used when linking reward information)
ㆍ Choose between using a custom code (specified term) or a fixed prefix depending on the type


Item Coupon Issuance
ㆍ Issue up to 50 items by selecting them (for bulk issuance such as attendance rewards)
ㆍ Default is issuance by member number; issuance based on character number is possible (only for representative coupons + item properties)


Discount Coupon Issuance
ㆍ Set fixed amount or fixed rate (Fixed amount = specific items only, Fixed rate = all items only)
ㆍ Fixed amounts are automatically calculated based on the dollar (reflecting the exchange rate on the last day of the previous month)
ㆍ Cart and bundle discounts are store-exclusive



Discount Cost Sharing
ㆍ Discount costs and affiliate fees can be set to be shared between the platform and the CP company
ㆍ Consultation with the person in charge is mandatory as it affects settlement


Step 3. User Delivery

Deliver codes via events, SNS, or CS; account-based or download coupons are loaded automatically.

Receiving Event Participation Rewards



Step 4. User Receipt

Register in the in-game coupon input window or check automatically in the coupon box to receive rewards (items/discounts).

In-game Coupon Registration Example



In-game Discount Coupon Usage Example
ㆍ Unlike store discount coupons, in-game discount coupons are used at the checkout screen.


Exposure Locations by Platform/Channel

Platform/Channel Exposure Location Notes
Mobile (Android) In-game [Register Coupon] button → SDK coupon popup Recommended for Android
Mobile (iOS) In-app exposure not recommended In-app input UI or connection to external web may cause rejection (Apple Guidelines)
PC (Windows) In-game [Register Coupon] button → SDK popup or STOVE/Game official website SDK popup only for multi-platform games
STOVE Official Website My Info > Coupon Box Integrated coupon input, login required
Game Official Website STOVE Coupon API integration in custom UI API call required, design customization possible

Development


Mobile (SDK) - Coupon Usage

Coupon usage is completed with a single call of View.useCoupon.
The SDK requests usage processing from the STOVE ItemBox server and handles the flow leading to the game server callback (item delivery).
Coupon box list search, detail inquiry, and coupon box coupon usage are server REST API areas, not SDK, so please refer to the 서버 연동 - 아이템박스(Itembox) section.

Caution for iOS Implementation
Under Apple Guidelines, exposing an in-app coupon input UI may be a cause for rejection.
Do not expose the in-game coupon input screen in iOS builds.

Prerequisites

  • User login must be completed.
  • Popup information must be registered in Partners for it to function properly. (Excluding direct call page method)

Notice
Partner settings are handled through the publishing technical representative.

Development Flow

  1. Coupon Number Collection
    : Receive the coupon number entered by the user in the in-game coupon input screen.
  2. Coupon Usage Call
    : Calling View.useCoupon(context, code, callback) triggers the SDK to process usage on the ItemBox server.
  3. Result Handling
    : Branch success/failure based on the Result delivered via callback.
    : If it fails, delegate to OperationUI.HandleResult(result, ...) to display the SDK common guide screen.

Troubleshooting

  • ErrorCodes
    DomainErrorCodeDescriptionAction
    com.stove.server100Coupon only available at PC cafesDisplay a message about the usage environment and keep the input screen open.
    com.stove.server997Not Verify AccessTokenAuth.accessTokenPlease re-query and call again. If the same error persists, guide the user to the login flow to have them re-issue the token.
    com.stove.server998Expired AccessTokenGuide the user to the login flow to have them re-issue the token.
    com.stove.server999System Error—
    com.stove.server2605This membership account cannot be used.—
    com.stove.server5031Daily authentication limit exceeded.Display an information message and guide the user to retry after a certain period.
    com.stove.server5105Invalid coupon number.Display a message to double-check the coupon number and reset the input screen.
    com.stove.server5125Coupon already used.Reset the input screen and display a usage completion message.
    com.stove.server5130Coupon usage suspended.—
    com.stove.server5135Coupon expired.Reset the input screen and display an expiration message.
    com.stove.server5155Usage limit for this coupon exceeded.Reset the input screen and display an information message.
    com.stove.server5161Coupon registration period expired.—
    com.stove.server5162Coupon not available in this country.—
    com.stove.server5164Coupon not available in this world.—
    com.stove.server5165Coupon only available in the coupon box.—
    com.stove.server5169Coupon usage period not active.—
    com.stove.server5200Not eligible for this coupon.—
    com.stove.server5202Coupon already registered in the coupon box.—
    com.stove.server6002This coupon number can no longer be used.—
    com.stove.server6026Usage limit exceeded.Reset the input screen and display an information message.

Cases with clear user guidance
For invalid coupon numbers (5105), already used coupons (5125), expired coupons (5135), and usage limit exceeded (5155 / 6026), display them as in-game information messages.
Since retrying is meaningless for already expired/used coupons, reset the input screen.

Sample Code

csharp
public void UseCoupon()
{
    /**
     * code : 쿠폰 입력 (string)
     **/
    View.UseCoupon("code", (Result result) =>
    {
        if (result.IsSuccessful)
        {
        }
        else
        {
            OperationUI.HandleResult(result, (Result operationResult) =>
            {
                /** ex) 현재 화면 유지 **/
            });
        }
    });
}

Android also supports the SDK-provided input UI
ViewUI.couponWhen you call this, the standard Stove coupon input screen will appear, and once the user enters the code, the SDK will continue to handle the usage processing and item distribution.
(Android only, not supported on iOS) For detailed usage and sample code, refer to 인게임 기능 — 쿠폰 사용 (Android만 가능).

PC (PCSDK) - Coupon Popup

You can use the coupon popup API provided by PCSDK ViewSDK to display the Stove coupon input screen within the game client.
When a user enters a coupon number directly in the popup, Stove handles the usage processing and item distribution flow.

The PC SDK coupon popup can only be used in multi-platform (PC + Mobile) games.
It only works for games registered as mobile games and designated for multi-platform use in Partners > Publishing Center > Game Entry Management > Game Basic Information Management.
If it is a single-platform (PC only) game, you must create your own coupon input UI in the game and replace it with a flow that calls the coupon registration API directly.

Prerequisites

  • After BaseSDK initialization (Base_Initialize or Base_InitializeEx) is complete, you can initialize ViewSDK (View_Initialize) to use the coupon popup API.
  • Base_RunCallback() must be called periodically in the game loop for asynchronous callbacks to work.
  • If you are using the built-in WebView (WebViewMode::INTERNAL) popup, initialize it by passing the game's main View_Initialize instead of View_InitializeWithWndInfo(mainWndHandle) to HWND.

Development Flow

  1. Initialization
    : After completing BaseSDK initialization with Base_Initialize (or Base_InitializeEx), call View_Initialize(). If using the built-in WebView popup, initialize it by passing the game's main View_Initialize instead of View_InitializeWithWndInfo(mainWndHandle) to HWND.
  2. Call Coupon Popup
    : Call View_CouponPopup or View_CouponPopupEx at the moment the user requests the coupon input UI.
    • C/C++ : Call View_CouponPopup(mode, onFinished). To receive the popup close event, use View_CouponPopupEx(mode, onFinished, onDestroy). mode is the WebViewMode value.
    • C# : Call View_CouponPopup(mode, onFinished) or View_CouponPopupEx(mode, onFinished, onDestroy).
    • onFinished is called when the popup display is complete, and onDestroy is called when the popup's native resources are completely cleared.
  3. Select WebViewMode
    : Set the mode that fits your game environment in mode between WebViewMode::EXTERNAL (external browser) or WebViewMode::INTERNAL (SDK built-in WebView).
    : Exclusive fullscreen mode games must use WebViewMode::EXTERNAL.
  4. Termination Processing
    : Receive the onDestroy callback to resume the game flow. If inventory refresh is needed after using the coupon, perform it after this callback.
  5. Cleanup
    : When finished using the coupon popup, clean up ViewSDK with View_UnInitialize(), and call Base_UnInitialize() just before the game terminates.

Troubleshooting

SituationCauseSolution
No response when calling the coupon popupThe coupon popup is a feature exclusively for multi-platform (PC + Mobile) games. It will not work if called in a game registered as single-platform in Partners.You must check if the game is registered as multi-platform in Partners. If it is a single-platform game, you can replace it with a flow that displays the game's own coupon input screen.
The coupon popup is hidden behind the game windowIf you initialize with View_Initialize without a parent window handle, the popup may appear as a separate window and go behind the game window. In Exclusive fullscreen mode, the built-in WebView (WebViewMode::INTERNAL) mode popup cannot appear above the game window due to Windows API limitations.View_InitializeWithWndInfo(mainWndHandle) You must initialize by passing the game's main HWND. If it is an Exclusive fullscreen mode game, the popup must be an external browser (WebViewMode::EXTERNAL) mode, there is no problem.
#include "ViewSDK.h"

using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;
using namespace Stove::PCSDK::View;

// 1) ViewSDK 초기화 (Base_Initialize 완료 이후)
auto initResult = View_Initialize();
if (!initResult.IsSuccessful())
{
return;
}

// 2) 쿠폰 팝업 (Ex 버전: 종료 이벤트 수신)
View_CouponPopupEx(
WebViewMode::EXTERNAL,
[](CallbackResult openResult)
{
if (openResult.GetResult().IsSuccessful())
{
// 팝업 열림 처리
}
},
[](CallbackResult destroyResult)
{
// 팝업 종료 시 게임 흐름 재개
}
);

// 3) 종료 시 정리
View_UnInitialize();
| === "Unity" |cs
using static Stove.PCSDK.Base;
using static Stove.PCSDK.View;

Result initResult = View_Initialize();
if (!initResult.IsSuccessful())
{
return;
}

OnPopupFinished onOpen = (callbackResult) =>
{
if (callbackResult.result.IsSuccessful())
{
// 팝업 열림 처리
}
};
OnViewPopupDestroyFinished onDestroy = (callbackResult) =>
{
// 팝업 종료 시 게임 흐름 재개
};
View_CouponPopupEx(WebViewMode.EXTERNAL, onOpen, onDestroy);

text

<div style="margin-top:10px;"></div> | | ### Server Integration - Itembox | | If a user participates in an event, the game server must be integrated to receive and process reward payment requests. | The reward payment request is delivered as a real-time Callback Notification from the Stove ItemBox server, and the game server should receive the request and process the appropriate reward payment. | |<div style="margin-top:24px;"></div> | | #### Prerequisites | The following items must be registered in advance through Partners | |1. **Select ItemBox Integration Type**: 
Select "Call from Stove server to game server (including Transaction Id)". 
Location: `파트너스 > 퍼블리싱 센터 > 게임 입점 관리 > 모바일 환경 설정`
<img src="https://static-resource.onstove.com/live/application_no/STATIC/developer-center/MOBILE2/itembox_img_13_1705281679968.png" style="width:600px;">

<br />
    2. **Register Basic World**: 
Even if your game does not require worlds, you must specify a basic world. (e.g., world_kr, etc.). 
Location: `파트너스 > Launching > SDK 실행 환경(MO) > 월드/채널 정보 탭`
<img src="https://static-resource.onstove.com/live/application_no/STATIC/developer-center/MOBILE2/itembox_img_10_1705281679687.png" style="width:900px;">

<br />
    3. **Register Callback Server URL**: 
Register the callback server URL that will receive item delivery requests. 
Location: `파트너스 > GM > 서비스 연동 > 아이템박스 연동 환경(mo)`
<img src="https://static-resource.onstove.com/live/application_no/STATIC/developer-center/MOBILE2/itembox_img_11_1705281679854.png" style="width:900px;">


::dc-callout{type="info"}
::

How to set up Loop back URL
The callback server (URL) should be prepared by the CP, but if it is not ready and you need to perform partner testing, you can use the Loop back URL setting below.
Sandbox: http://i-api.gate8.com/itembox/v2/item/inboundReward
ACL work is required for communication with ItemBox. The Stove platform does not require a separate service open policy, but please ensure that you perform Inbound open work for the game server only.

Item Delivery API

This explains the API integration specifications that must be provided by the CP.


API Integration Information

text
POST {파트너스 등록 URL 정보}
Content-Type: application/json

Request

  • Body
NameTypeRequiredExampleDescription
msg_idStringYbaf84a85-abcc-49fc-ba85-54b7c38331e9msg ID is generated every time it is sent from ItemBox to the game server
(unique per transmission)
msgStringY"aWLoj83ZxAICnRfjA+ayhd7nn1V/Fh/3I....3Of7N0s45uDN6DJjAjwqc="Encrypted delivery, decryption required
timestampLongY1480512039Msg Timestamp (seconds from January 1, 1970 to current time)
  • msg payload before encryption
NameTypeRequiredExampleDescription
game_idStringYStove_GAMEGame ID
world_idStringYworld_globalWorld ID
member_noLongY503510Platform user's guid (member_no for legacy games)
nickname_noLongY1603829809Platform user's nickname_no
item_idStringYITEM_K001Game item ID
transaction_idStringY6b384ab9d65f422db0abf186a7f79311transaction id (transaction key value, used by game server to determine duplicate delivery)
service_typeStringYCOUPONService type
"COUPON" : Sent via coupon usage
"EVENT" : Sent via event
item_amtIntegerY3Item quantity
reward_msgStringNThis is a reward for participating in the pre-registration eventMessage to show to the user when the item is delivered
(Content registered when creating a Coupon)
end_dtStringN20150116Item delivery expiration date (DateFormat: "yyyyMMdd", Default: 1 month after request time)
payloadObjectN{
"item_period" : 0
}
ItemBox delivers data required by the CP in this json object
(For example: If there are permanent, 7-day, 30-day, and 60-day options for a time-limited item



Response

The game server must respond (in application/json format) to the ItemBox Call API using the return codes specified below.
Content-Type : application/json


  • Body
NameTypeRequiredExampleDescription
return_codeIntegerY0처리 결과 코드
return_messageStringYOK처리 결과 메시지 - 50자 이내 결과 식별 가능한 메세지 전달

  • Return Code
Return codeHTTP Status CodeDescription아이템박스 동작 및 재처리 여부
0200 ok지급 성공 (이미 지급한 transaction_id일 경우도 동일)지급 성공
40001200 ok서버 내부 오류 (API 재호출 시 아이템지급 가능한 케이스의 경우 사용)지급 실패 - 재처리 진행
40002200 ok요청한 아이템 없음지급 실패 - 재처리 미진행
40003200 ok이용자 정보 불일치지급 실패 - 재처리 미진행
40004200 ok메세지 복호화 실패지급 실패 - 재처리 미진행



Sample

  • Request
    • 암호화하지 않은 상태의 Request Body입니다. 실제 게임 서버로 전달 시 "msg" json value 부분이 암호화되어 전송됩니다.
    • 복호화 순서는 전달받은 msg data를 BASE64 Decoding 처리를 하고 AES256 Decryption처리를 하셔야 합니다.
    json
    {
        "msg_id": "baf84a85-abcc-49fc-ba85-54b7c38331e9",
        "msg" :
        {
            "game_id":"STOVE_GAME",
            "world_id":"world_global",
            "member_no": 503510,
            "nickname_no": 1603829809,
            "item_id": "ITEM_K001",
            "transaction_id":"6b384ab9d65f422db0abf186a7f79311",
            "service_type":"COUPON",
            "item_amt":3,
            "reward_msg":"사전등록 이벤트 참여 보상입니다",
            "end_dt":"20150116",
            "payload":
            {
                "item_period":0
            }
        },
        "timestamp": 1480512039
    }
    
  • Response
    json
    - Content-Type : application/json
    {
        "return_code": 0,
        "return_message": "성공했습니다."
    }
    



Decryption Process

  • To ensure the stability and validity of requests between the ItemBox system and the game server, some data (Json Data - msg values) is encrypted during transmission. Decryption is required to verify the message body.
  • Encryption method: AES256
  • Decryption key: Client Secret Key
  • Transformation: AES/CBC/PKCS5Padding
  • IV Spec: First 16 characters of the 'Client Secret Key' value
  • Decryption sequence: You must perform BASE64 Decoding on the received msg data and then perform AES256 Decryption.
  • Secret Key location: 파트너스 > 퍼블리싱 센터 > 게임 입점 관리 > 플랫폼 연동 키 > 모바일 서비스 연동 키 > 클라이언트 Secret Key



Duplicate Delivery Prevention

  • transaction_id is a unique value automatically generated when a delivery request occurs, and it is used to prevent missing item deliveries between the game server and ItemBox and to
    prevent duplicate deliveries.
  • If the reward delivery is successful, the game server must store the transaction_id in the game to manage it so that duplicate deliveries do not occur.
  • If a transaction_id that has already been delivered by the ItemBox server is requested, the game server should send "0" as the response Data "return_code".



Automatic Retry for Failed Requests

  • The STOVE ItemBox service performs a retry for failed transmissions if the transfer to the game server fails due to network issues/server errors, etc.,
    once every 10 minutes, up to 5 times. In this case, the "transaction_id" in the "msg" json is used as a classification key for failed cases, so the game server must
    store cases that have been successfully delivered and processed using the "transaction_id".
  • If the delivery was processed by the game server but was marked as failed by the ItemBox platform due to a missing response or network error,
    a re-delivery request may occur.

Troubleshooting

SituationCauseSolution
Item delivery API is not calledOccurs if all preparatory steps are not performed correctlyCheck through Partners to see if the preparatory settings were performed correctly.
Also, check if API calls from the outside are blocked at the CP server infrastructure level.
Message decryption failsOccurs if the decryption process is not performed correctly.Check the guide and the decryption process chapter, and integrate using the correct decryption key

Frequently Asked Questions



Q1. What is the difference between the direct payment method and the coupon box method?
A. The direct payment method is a method that requests the coupon reward to be paid directly to the game when the coupon is used.
The coupon box method is a method where coupons are registered and managed in the user's coupon box before being used, and it includes additional steps for checking the coupon list and viewing details.
Q2. Can I provide a coupon registration UI directly on iOS?
A. According to Apple guidelines, external reward input or pages that induce purchases are restricted, so they must be processed outside the app.
Please do not provide a direct coupon input function within the iOS app, and configure explicit bypass instructions to prevent policy rejection.
Q3. Can guest accounts also enter coupons?
A. If user identification is possible through STOVE authentication (GUID-based), coupon input is possible.
Q4. What happens if I map multiple items to one coupon?
A. If you map multiple items to one coupon, payment requests are sent to the game server for the number of mapped items.
Please create a package-like item required for rewards in-game so that only one payment request is received.
Q5. How can I prevent duplicate payments?
A. You must manage it by storing the transaction_id within the game to prevent duplicate payments.
If a transaction_id that has already been paid is re-requested from the ItemBox server, the game server should send "0" as the "return_code" in the response data.
Q6. What happens if the ItemBox Callback fails?
A. The STOVE ItemBox service performs an automatic retry up to 5 times, once every 10 minutes, if the transfer to the game server fails due to network failure/server error, etc.
Since the same transaction_id is used during retries, the game server can respond with a "0" return_code for items already processed without duplicate payment.
Q7. How should I handle item payment failures due to maintenance or errors?
A. There is a reprocessing function in the Partners menu, and for failed items, you can reprocess the payment in the Partners GM > Payment Failure Initialization (mo) menu.



Do you have any inquiries?