Curious about the actual application flow?

Usage Scenarios / Purchasing in the Game

Coupon

Understanding

By integrating the STOVE platform's coupon service, you can issue coupons in STOVE Partners and grant rewards such as items to users in the game or on the web.
Coupons are used to boost user retention through pre-registration/collab/event rewards, marketing-inflow/conversion tracking, manual CS rewards, and more.

Coupon Types and Rewards

Looking at coupon types and reward composition together helps you pick the right coupon for your situation.

First pick the coupon type that fits your situation.

Coupon-type selection guide

Does the user enter the code themselves?

The issuance method and the user's experience of receiving a coupon differ by coupon type.

If a coupon's type is "to whom · how to distribute," a coupon's attribute is "what to give."
When issuing, the order is to decide the type first, then set the attribute (reward).

"In this case, do this" — combinations that are actually used often.

This combination for this case

· Handing out items via SNS/collab → Representative (shared) coupon + item

· Per-person item grants / pre-registration / CS rewards → Standard coupon + item

· Granting items directly to a specific user (VIP/error rewards) → Account-grant coupon + item

· In-game payment-discount events → Standard or representative (shared) coupon + discount (users apply it at the payment window)

· Granting game passes to creators/promoters (offering trials) → Account-grant coupon + game pass

Screen Examples by Setting

The screen and experience users see in-game differ by coupon type and detailed settings.

Coupon Issuance Flow

This is the full flow from issuing a coupon to delivering it to users.

Step 1. Set coupon info

In Partners [Billing > Coupon Management > Coupon Info Settings], enter the coupon type, reward, representative image, etc.

ℹ️ This step only needs to be set once. Once set, you don't need to redo it each time you issue, and you only edit it when you want to change settings like type or reward. Actual coupon issuance repeats from Step 2.

Step 2. Issue the coupon

In Partners [Billing > Coupon Management > Issue Coupon], set basic info like the coupon name and the type/attribute.

Step 3. Deliver to users

Deliver the code via events/SNS/CS, etc.; account-grant and download coupons are loaded automatically.

Receiving event-participation rewards

Step 4. User receipt

Registering it in the in-game coupon-input window or auto-checking it in the coupon box grants the reward (item/discount).

In-game coupon-registration example

Display location by platform/channel

Development

Mobile (SDK) - Using Coupons

Using a coupon is done with a single call to the SDK-provided View.useCoupon. The SDK requests use-processing from the STOVE ItemBox server and handles the flow through to the game-server callback (item grant). Coupon-box list search, detail lookup, and coupon-box coupon use are in the server REST API domain, not the SDK, so see the Server Integration - ItemBox section.

Prerequisites

• The user must be logged in.
• Pop-up info must be registered in Partners for it to work (except for the direct-call page method).

Development Flow

1. Collect the coupon number : Receive the coupon number the user entered in the in-game coupon-input screen.
2. Call coupon use : Calling View.useCoupon(context, code, callback) has the SDK process the use with the ItemBox server.
3. Handle the result : Branch success/failure with the Result passed in the callback. : On failure, delegating to OperationUI.HandleResult(result, ...) shows the SDK's common guidance screen.

Troubleshooting

• ErrorCodes

  Domain	ErrorCode	Description	Action
  com.stove.server	100	A coupon usable only in a PC cafe	Show a usage-environment notice and keep the input screen open.
  com.stove.server	997	Not Verify AccessToken	Re-fetch Auth.accessToken and call again. If the same error persists, guide the user into the login flow to get a reissued token.
  com.stove.server	998	Expired AccessToken	Guide the user into the login flow to get a reissued token.
  com.stove.server	999	System Error	—
  com.stove.server	2605	This membership account cannot use it.	—
  com.stove.server	5031	You've exceeded the daily verification count.	Show a notice and guide the user to retry after a while.
  com.stove.server	5105	Invalid coupon number.	Show a re-check-the-coupon-number message and reset the input screen.
  com.stove.server	5125	This coupon has already been used.	Reset the input screen and show an already-used notice.
  com.stove.server	5130	This coupon has been disabled.	—
  com.stove.server	5135	This coupon has expired.	Reset the input screen and show an expiry notice.
  com.stove.server	5155	You've exceeded this coupon's usage limit.	Reset the input screen and show a notice.
  com.stove.server	5161	This coupon's registration period has expired.	—
  com.stove.server	5162	This coupon can't be used in your country.	—
  com.stove.server	5164	This coupon can't be used in this world.	—
  com.stove.server	5165	This coupon can only be used from the coupon box.	—
  com.stove.server	5169	It's not within this coupon's usage period.	—
  com.stove.server	5200	You're not an eligible target for this coupon.	—
  com.stove.server	5202	This coupon is already registered in the coupon box.	—
  com.stove.server	6002	This coupon number can no longer be used.	—
  com.stove.server	6026	The usage count has been exceeded.	Reset the input screen and show a notice.

Sample Code

public void UseCoupon()
{
    /**
     * code : coupon input (string)
     **/
    View.UseCoupon("code", (Result result) =>
    {
        if (result.IsSuccessful)
        {
        }
        else
        {
            OperationUI.HandleResult(result, (Result operationResult) =>
            {
                /** ex) keep the current screen **/
            });
        }
    });
}

PC (PCSDK) - Coupon Pop-up

Using the coupon pop-up API provided by PCSDK ViewSDK, you can show the STOVE coupon-input screen inside the game client. When the user enters the coupon number directly in the pop-up, STOVE proceeds with the use-processing and item-grant flow.

Prerequisites

• After BaseSDK initialization (Base_Initialize or Base_InitializeEx) completes, initializing ViewSDK (View_Initialize) lets you use the coupon pop-up API.
• Base_RunCallback() must be called periodically in the game loop for async callbacks to work.
• If using a built-in WebView (WebViewMode::INTERNAL) pop-up, initialize with View_InitializeWithWndInfo(mainWndHandle), passing the game's main HWND, instead of View_Initialize.

Development Flow

1. Initialization : After completing BaseSDK initialization with Base_Initialize (or Base_InitializeEx), call View_Initialize(). If using a built-in WebView pop-up, initialize with View_InitializeWithWndInfo(mainWndHandle), passing the game's main HWND, instead of View_Initialize.
2. Call the coupon pop-up : When the user requests the coupon-input UI, call View_CouponPopup or View_CouponPopupEx.
   • C/C++ : call View_CouponPopup(mode, onFinished). To also receive the pop-up-close event, use View_CouponPopupEx(mode, onFinished, onDestroy). mode is a WebViewMode value.
   • C# : call View_CouponPopup(mode, onFinished) or View_CouponPopupEx(mode, onFinished, onDestroy).
   • onFinished is called when the pop-up finishes displaying, and onDestroy when the pop-up's native resources are fully cleaned up.
     
3. Choose WebViewMode : Set mode to WebViewMode::EXTERNAL (external browser) or WebViewMode::INTERNAL (SDK built-in WebView), whichever fits your game environment. : Exclusive-fullscreen games must use WebViewMode::EXTERNAL.
4. Handle close : Receive the onDestroy callback to resume the game flow. If you need to refresh the inventory after coupon use, do it after this callback.
5. Cleanup : When done with the coupon pop-up, clean up ViewSDK with View_UnInitialize(), and call Base_UnInitialize() just before the game exits.

Troubleshooting

Sample Code

#include "ViewSDK.h"

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

// 1) Initialize ViewSDK (after Base_Initialize completes)
auto initResult = View_Initialize();
if (!initResult.IsSuccessful())
{
    return;
}

// 2) Coupon pop-up (Ex version: receive the close event)
View_CouponPopupEx(
    WebViewMode::EXTERNAL,
    [](CallbackResult openResult)
    {
        if (openResult.GetResult().IsSuccessful())
        {
            // Handle pop-up open
        }
    },
    [](CallbackResult destroyResult)
    {
        // Resume the game flow when the pop-up closes
    }
);

// 3) Clean up on exit
View_UnInitialize();

Server Integration - ItemBox

When a user participates in an event, the game server must be integrated to receive and process reward-grant requests. Reward-grant requests are delivered as real-time callback notifications from STOVE's ItemBox server, and the game server should receive the request and process the appropriate reward grant.

Prerequisites

The items below must be registered in advance through Partners

1. Select the ItemBox integration type: Select "Call from the STOVE server to the game server (including Transaction Id)". Location: Partners > Launching > Service Integration > SDK Runtime Environment Settings

2. Register a default world: Even games that don't need worlds must designate a default world. (e.g., world_kr). Location: Partners > Launching > SDK Runtime Environment (MO) > World/Channel Info tab

3. Register the callback server URL: Register the callback server URL that will receive item-grant requests. Location: Partners > GM > Service Integration > ItemBox Integration Environment (mo)

How to set up a loopback URL
The callback server (URL) must be prepared by the CP company, but if it's not ready yet and you need to test in Partners, you can use the loopback URL setup below.
Sandbox: http://i-api.gate8.com/itembox/v2/item/inboundReward
ACL work is needed to communicate with ItemBox. The STOVE platform doesn't need a separate service-opening policy; only the game server must perform the inbound-opening work.

Item-Grant API

This describes the API integration spec that the CP company must provide.

API integration info

POST {URL info registered in Partners}
Content-Type: application/json

Request

• Body

• msg payload before encryption

Response

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

• Body

• Return Code

Sample

• Request
  • This is the Request Body in unencrypted form. When actually sent to the game server, the "msg" json value part is encrypted.
    
  • For decryption, take the received msg data, apply BASE64 Decoding, and then apply 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":"This is a reward for pre-registration event participation",
          "end_dt":"20150116",
          "payload":
          {
              "item_period":0
          }
      },
      "timestamp": 1480512039
  }
  

• Response
  json

  - Content-Type : application/json
  {
      "return_code": 0,
      "return_message": "Success."
  }
  

Decryption (decrypt) process

• To ensure stability and validity of requests between the ItemBox system and the game server, some data (Json Data - msg values) is encrypted when sent. Decryption is needed to read the message body.
• Encryption (encrypt) method: AES256
• Decryption (decrypt) key: Client Secret Key
• Transformation: AES/CBC/PKCS5Padding
• IV Spec: the first 16 characters of the 'Client Secret Key' value
• Decryption order: take the received msg data, apply BASE64 Decoding, then apply AES256 Decryption.
• Secret Key location: Partners > Launching > Service Integration > Platform Integration Keys > Mobile Service Integration Key > Client Secret Key

Duplicate-grant protection

• transaction_id is a unique value auto-generated when a grant request occurs; it's used to prevent missed and
  duplicate item grants between the game server and ItemBox.
• On successful reward grant, the game server must store the transaction_id in-game and manage it to prevent duplicate grants.
• If the ItemBox server requests an already-granted transaction_id, the game server can just send response Data "return_code" as "0".

Automatic re-request for failures

• If sending to the game server fails due to a network failure/server error, the STOVE ItemBox service retries the failed case
  once every 10 minutes, up to 5 times. In this case, the "transaction_id" in the "msg" json is used as the distinguishing key for the failed case, so the game server
  must keep a record of cases successfully granted and processed by "transaction_id".
• If the game server processed the grant but the ItemBox platform treated it as failed due to a missing reply or a network error,
  a re-grant request can occur.

Troubleshooting

Frequently Asked Questions