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

Payment

Understanding


Payment Support Overview

STOVE supports two types of payments: PC online payment and mobile market payment.
Supported currencies, payment methods, limits, and cancellation methods vary depending on the payment type.

Payment Type Description
PC Online Payment Payment via web shop or in-game shop for PC version games (using the payment window provided by STOVE).
Mobile Market Payment Payment for games released on app markets such as Google or Apple (using the IAP (In-App Purchase) window provided by the market).

Payment Account Identity Verification
ㆍ Only accounts with minimal identity verification can make payments
ㆍ Korea: Identity verification / Global: Email verification

Payment for Games Distributed via Steam Launcher
Payments for games run via the Steam launcher also fall under PC online payment, but the payment window is replaced by the Steam payment overlay instead of the STOVE payment webview. For detailed flows, please refer to Developing → PC IAP → Steam Payment.

Payment Support Currencies

Category Currency Description Accounts paying in this currency
PC Online PaymentKRWSouth Korean WonAccounts registered in Korea
USDUS DollarAccounts registered in the US, and accounts registered in countries without supported currencies
JPYJapanese YenAccounts registered in Japan
EUREuroAccounts registered in designated countries that use the Euro (see list below)
THBThai BahtAccounts registered in Thailand
PHPPhilippine PesoPhilippine registered account
TWDNew Taiwan DollarTaiwan registered account
Mobile market payment-Supported currencies for market paymentPayment in the supported currency set for each user's market account

※ List of countries where Euro payment is applied (as of 2026)37 countries
Country NameCode Country NameCode Country NameCode
GermanyDEEstoniaEEAland IslandsAX
FranceFRLatviaLVSaint BarthelemyBL
ItalyITLithuaniaLTFrench GuianaGF
SpainESLuxembourgLUGuadeloupeGP
Portugal (Portugal)PTCyprus (Cyprus)CYSaint MartinMF
Netherlands (Netherlands)NLMalta (Malta)MTMartiniqueMQ
Belgium (Belgium)BECroatia (Croatia)HRSaint Pierre and MiquelonPM
Austria (Austria)ATAndorra (Andorra)ADRéunionRE
Finland (Finland)FIMonaco (Monaco)MCFrench Southern TerritoriesTF
Ireland (Ireland)IESan Marino (San Marino)SMMayotteYT
Greece (Greece)GRVatican City (Vatican City)VABulgaria*BG
SlovakiaSKKosovoXK
SloveniaSIMontenegroME

Payment Currency Notice
ㆍ Bulgaria: USD payment and point accumulation provided
ㆍ The payment currency for the same product must be registered identically in both the store and the billing system to process payments (e.g., if registered differently, such as Store EUR and Billing USD, payment will not be possible)

Supported Payment Methods

Category Country Description
PC Online Payment South Korea STOVE Pay(Default): Easy payment via bank transfer/credit card, higher single-transaction limit, and higher point accumulation
Others: Easy payment via KakaoPay, Naver Pay, Toss, Payco, etc., mobile phone, and gift certificates
Global Major payment methods: PayPal, Credit/Debit Card, ApplePay, etc. Additional local payment methods provided by country (e.g., PayPay in Japan)
Mobile Market Payment All Countries Payment via the method registered to the user's market account (The configuration of methods is determined by the market and cannot be influenced by STOVE or the partner company)

Payment Gateway (PG) Redundancy
ㆍ Major payment methods are linked to 2 or more PGs → Automatic switch in case of failure

Minor Payments
ㆍ Only gift certificates are available by default; all other methods require guardian consent
ㆍ Guardian consent: Verification of age difference of 20 years or more via identity authentication (The guardian does not need to be a member, valid for 12 months)

Payment Limits

There is a monthly payment limit per game, and the criteria vary depending on the country and platform.

Category Country Description
PC Online Payment South Korea PC online game limits applied in accordance with Ministry of Culture, Sports and Tourism self-regulation
ㆍ Adults: Self-set between 100,000 KRW and 30 million KRW (3 times per month, changeable after mobile phone identity verification)
  ㆍ The set limit is aggregated based on the account holder (resident registration number) and applied per game each month
ㆍ Minors: 70,000 KRW monthly limit, cannot be changed
Global No default limit (however, there may be limits on the payment method itself)
ㆍ 1-time, 1-day, and 1-month limits per game can be set by currency
Mobile Market Payment All Countries No payment limit (however, there may be limits on the payment method itself)
PC Online + Market Payment Japan Purchase limits by age group
Applied to games serviced in Japan (de facto regulation under the Electronic Financial Transactions Act)
ㆍ For multi-platform games, PC and mobile market purchase amounts are aggregated
ㆍ 15 years old or younger: 5,000 JPY per month
ㆍ 16 to 17 years old: 30,000 JPY per month
ㆍ 18 years old or older: No limit
ㆍ ※ As of April 2022, the age of adulthood under Japanese Civil Code changed from 20 to 18

Japan Payment Limit Calculation Method
ㆍ Aggregation of cumulative "JPY" payment amounts from the 1st to the last day of the current month (excluding coupons/points)
ㆍ Regular Member PC: If the registered country is Japan (Japan registration = JPY payment)
ㆍ Regular Member Mobile: Only when the registered country is Japan and the payment currency is JPY, the actual JPY payment amount is aggregated
ㆍ Guest PC: Not applicable as there are no guest members on PC
ㆍ Guest Mobile: Since the registered country cannot be determined, the actual JPY payment amount is aggregated only when the payment currency is JPY
ㆍ All in-game payment amounts are aggregated (includes all products, not just currency-type items)
ㆍ If the amount of the product to be purchased exceeds the remaining limit, that product cannot be purchased (only products that can be purchased within the remaining limit are possible)

Special Limits by User
ㆍ Special limits can be granted to specific users (based on member number) (marketing, influencers, etc.)
ㆍ If there is a conflict with the game limit, the user's special limit is applied first

Payment Confirmation and Proof

Category Description
PC Online Payment Check on STOVE platform
ㆍ Email notification upon completion of payment/purchase (not sent if no information is available)
  ㆍ Real-time: Personal payment history (guardians can also check their child's payment history)
  ㆍ Monthly: Personal payment history for the previous month (guardians can also check their child's payment history)
ㆍ Check payment history and accumulated point history in 'My Info'
Mobile Market Payment Check in each market
ㆍ Check payment information via payment notification history, invoice, or receipt

Cash Receipt Processing
ㆍ PC Online Payment: Processed by the payment gateway (PG), can be checked on the National Tax Service website
ㆍ Mobile Market (Google Wallet): STOVE automatically issues cash receipts

Payment Cancellation

Category Description
PC Online Payment Store/Item Payment (Korean payment method)
Refunds are determined based on whether the subscription withdrawal period has passed or the product value has been damaged (periods vary by game)
ㆍ Within period + Unused: Cancellation of original payment method approval
ㆍ Within period + Used: Partial refund
ㆍ Period passed + Unused: Partial refund after deducting the larger amount between 1,000 KRW and a 10% fee
ㆍ Period passed + Used: Refunds may be restricted according to game policy

Store/Item Payment (Global payment method)
ㆍ Within approval cancellation period: Cancellation of original payment method approval
ㆍ Approval cancellation period expired: Cancellation not possible

Store Games
ㆍ Purchase cancellation is possible within 14 days of purchase + less than 2 hours of cumulative playtime
ㆍ Upon cancellation, STOVE Cash will be refunded, and the refunded cash can be requested for a separate cash refund
Mobile Market Payment Refunds are determined based on whether the subscription withdrawal period has expired or the product value has been damaged

Integration with Billing System

This guide explains how to integrate payment (IAP) features into your game using the STOVE SDK.
It provides integrated support for in-app payments from major markets such as Google Play and the Apple App Store, as well as PC online payments, and covers the entire payment flow, including subscription products and abnormal refund processing.

Billing System Configuration

The STOVE billing system consists of a client SDK and server middleware.

System Name Description
MultiPlatform-Middleware
(Cross-platform middleware)
A GATEWAY server responsible for communication between the game and billing (online/mobile).
IAP Mobile billing server.
Bill-WEB API Online billing server.
Game Server Game server.

Supported Features

Feature Description
Payment Completion Notification Stove Billing sends a notification to the game server upon completion of payment (online/mobile).
A completion response is required after verifying validity via middleware.
Payment Validity Verification Stove Billing verifies the source of the received payment notification.
Supports BULK (list) processing.
Game Cash Balance Check Inquiry of paid cash balance managed by the game.
Abnormal Refund Handling Collects details of refunds made directly by users through the market and delivers them to the game server.
Supports Google and Apple markets.
Subscription Products Supports auto-renewing subscription products for Google Play and Apple App Store.

Prerequisites

For normal billing operations, all the information below must be registered in Partners.
If even one item is missing, payments will not process correctly.

Category Registration Details
Billing Integration Info Billing Version (V4), Service Type, GUID Usage, Payment Completion Notification URL, Cash Inquiry URL
IAP Info by Market Google/Apple Market Authentication Info
Market Product Info Product ID by market
World Info Default world (world_id) for Noti URL

Caution regarding market integration info
ㆍ Apple IAP Key: Cannot be re-downloaded after initial download (must be reissued if lost)
ㆍ If the Apple shared secret is regenerated, all app information currently in use must be updated

Abnormal Refund Handling

This is a feature that prevents users from continuing to use received items if they request a refund (cancellation) directly through the market without going through an operator after receiving the items.
For this, Stove Billing responds in two stages: a stage to intervene before the refund is finalized to prevent abuse and a stage to recover losses after the refund is finalized.

Stage Purpose Applicable Markets
Stage 1
Refund Review
Intervene before the market confirms a refund to prevent refunds for items already consumed or sold (refund abuse). Google Play, Apple App Store
(Steam is not supported as it lacks a pre-feedback process)
Stage 2
Refund Repayment
If the market forces a refund despite a rejection in Stage 1, recover the loss by requiring the user to pay again upon their next login. Google Play, Apple App Store, Steam

Cases not blocked in Stage 1 proceed to Stage 2
If the market forces a refund without reflecting the developer's (Stove) opinion, the case is moved to Stage 2 (Refund Repayment). Both functions operate independently but are connected sequentially.

Abnormal Refund Collection Targets
ㆍ Stage 1 (Refund Review): General item refund requests on Google Play/Apple App Store
ㆍ Stage 2 (Refund Repayment): Confirmed refunds on Google Play/Apple App Store/Steam
ㆍ Mobile Subscription Items: Excluded as abnormal refund judgment is not possible
ㆍ Information is also delivered if a refund occurs for a user who has withdrawn from the game

Development


Partners and Console Settings

  • Google Console API Settings
      1. Obtain Google Play Console API access rights
      1. Create a Google Cloud project (Create project / Add API / Configure OAuth consent screen and create client ID)
      1. Generate OAuth 2.0 Playground Refresh Token
      1. Enter Stove Partners billing setting information

  • Billing Information Entry Guide
    • Register Google Play billing information (Market verification key / OAuth Client ID / OAuth Client Secret / Refresh Token / Bucket Name / Credential json)
    • Register Apple App Store billing information (Issuer ID / Key ID / IAP Key / Shared Secret)

  • Non-Approved Refund Item History Reception Settings
    • iOS App Store notification settings (QA/Production server URL / Version 2 notification change)
    • Android notification settings

SDK Integration

Mobile IAP

Android uses PlayBilling, and iOS uses StoreKit to handle the payment flow. While the SDK connects market calls to Stove billing server verification, you must separately implement payment notification (Noti) reception, re-verification, and fulfillment processing on the game server side.

Prerequisites
  • Module Dependencies
    • Android (build.gradle): Add the following repository and dependencies. (Check and apply the latest release version.)
      groovy
      repositories {
          google()
          jcenter()
          maven {
              url "https://externalnexus.iam0.com/repository/mvp"
              // Android Gradle Plugin 7.0 이상 사용 시 아래 옵션 추가
              allowInsecureProtocol = true
          }
          mavenCentral()
      }
      
      dependencies {
          implementation 'com.stove:iap-google:2.9.0'
      }
      
    • iOS (Xcode Capabilities): Search for and add In-App Purchase in Build Settings → Capabilities and ensure it is enabled.
  • Register Partners Billing Information: Google Play / Apple App Store billing keys and secrets must be registered in Partners. (Refer to 2. 연동 가이드 > Google Play 연동 / Apple App Store 연동)
  • Register Payment Notification (Notification) URL: Register the URL for receiving payment notifications on the game server side in Partners. After the SDK payment is completed, the fulfillment request is sent to this URL. (Mobile supports up to 100 retries)
  • User Login Complete: All IAP calls only function after Auth.login is complete. If called while not logged in, Auth.UnauthorizedError (30002) is returned.
  • When using Multi-Character (Multi-Currency): Configure use_custom_billing_guid (true) in the Partners SDK Config. The client must call setCustomBillingGUID immediately after IAP initialization + when world/character selection is complete. (Refer to the Required Multi-Character (Multi-Currency) Management Settings section in the sample code below)
Development Flow
  1. Initialization: Call IAP.initialize after login is complete. If it fails with Auth.UnauthorizedError (30002), guide the user to the login flow; if it fails with IAPError.InitializeError (40003), guide the user to check the market environment using userInfo's responseCode (BillingClient.BillingResponseCode) and debugMessage.
  2. Register Payment Listener: Register the payment result callback using IAP.setListener within the initialization success callback. Normal purchases, cancellations, account mismatches, pending verification, pending fulfillment, and market errors are all delivered to this listener.
  3. Store Configuration: Query the product list with IAP.fetchProducts, and branch the activation/deactivation of the purchase button based on the response IAPProduct's ProductState (Available / Waiting / Purchased) value.
  4. Proceed with Purchase: For Available items, call IAP.startPurchase. Since Waiting is in progress, deactivate the button, Purchased is in an unpaid state, so IAP.flush to process the re-payment.
  5. flush: When a payment has been made but there are undelivered items, or when the app is restarted, call IAP.flush to request consumption/re-payment. The result will be returned via the setListener callback.
  6. (Optional) Additional Features: Use the serviceOrderId argument to pass a developer payload, IAP.handleVoidedPurchases to check refund history, and purchasePromotion for iOS App Store promotional product payments.

Perform payment verification on the game server
Do not grant items based solely on the isSuccessful of the SDK callback. Since the client can be tampered with, the game server must perform a secondary verification using the Stove payment validity check API after receiving the payment notification (Noti) before granting currency/items.

Troubleshooting

Payment verification pending/delivery pending are part of the normal flow
IAPError.PurchasedError (40006) and IAPError.WaitingError (40001) are normal states where payment/delivery is processed asynchronously on the billing server. Do not inform the user of an error; instead, display a progress screen such as "Payment is being processed, we will notify you via push notification shortly." After a certain period, the billing server will process it automatically, and the result will be delivered via push notification.

Handling Account Mismatch (SuccessButUserMissMatch, 40000)
This occurs when a user changes their account or moves to a different world before payment verification is complete. Induce a re-login flow based on the currently logged-in account and inform the user that previous payment results will be processed later via game server notifications (Noti).

SituationCauseAction
Auth.UnauthorizedError (30002)Login incomplete or token expiredAuthUI.login or Auth.login to proceed with the re-login flow, then try calling IAP again.
IAPError.InitializeError (40003)Android market (PlayBilling) initialization faileduserInfo of responseCode (BillingClient.BillingResponseCode) and debugMessage to guide the user to check store app installation, login status, and supported market availability.
IAPError.InvalidProduct (40004)Attempting to pay with a manually created product object or a product other than the fetchProducts resultAlways pass the object received from IAP.fetchProducts as-is to startPurchase. Do not use a product that you have instantiated directly.
IAPError.MarketError (40002)Market client error during payment attemptBranch to userInfo.responseCode (BillingResponseCode) for Android and SKError.code for iOS to guide the user. Retry for temporary errors, and guide them to check the store app/account for environmental issues.
iOS pay country code nil (40010)Apple account payment country information missingGuide the user to register their country/region and payment information in App Store settings.
Server billing verification failed (30000 verify fail / 30015 sandbox transaction)Payment receipt verification failed or test account not registered in LIVE environmentIf in a LIVE environment, check if the test account is registered in Partners. For general cases, check the receipt re-verification logic on the game server.
Already subscribed product (93106)User already owns the same subscription productInform the user that they are already subscribed and disable the purchase button.
Payment delivery missingGame server notification (Noti) URL response failed or processing missedEnsure the notification URL registered in Partners always returns a 200 response. Since mobile attempts up to 100 re-deliveries, implement idempotent processing on the game server side as well.
Delivered to the wrong character in multi-charactersetCustomBillingGUID not called or called at the wrong timeCall setCustomBillingGUID("{STOVE_guid}_{STOVE_character_no}") after IAP initialization + at the point when world/character selection is complete.
40303 returned in refund history UIAuthentication token expiredDelegate to OperationUI.HandleResult and perform a forced logout via Auth.logout to induce a re-login.

A detailed ErrorCode table for each function is included in the sample code below.

Sample Code

Initialization

Initialize the Market SDK (PlayBilling/StoreKit). Product lookup and purchase calls are only possible after initialization is complete.

  • Recommended timing: After successful login

csharp
#if UNITY_ANDROID
using Stove.StoveSDK.IAP.Google;
#endif

public void Initialize()
{
    IAP.Initialize((Result result) =>
    {
        if (result.IsSuccessful)
        {
            SetListener(); // setListener 호출
        }
        else if (result.ErrorCode == Auth.UnauthorizedError)
        {
            //TODO : login
        }
        else
        {
            //InitializeError. Android Only
            // see https://developer.android.com/reference/com/android/billingclient/api/BillingClient.BillingResponseCode
        }
    });
}

ErrorCodes

DomainErrorCodeDescription
com.stove.success0Success
com.stove.auth30002UnauthorizedErrorResult
com.stove.iap40003InitializeError. For Android PlayBilling, refer to 'responseCode' and 'debugMessage' in userInfo
com.stove.iap40010Only for iOS, when the pay country code is nil
com.stove.server20001initialize fail on precheck
com.stove.server20002initialize fail on afterCheck
com.stove.server20003initialize fail on send tid
com.stove.server20004initialize fail on send tid : error parsing response



setListener

Sets the listener to receive payment results after successful IAP initialization. flush The processing results of are also delivered to this listener.

  • Recommended timing: Immediately after initialization is complete
  • product If there is a value, it changes the status of the product for which the purchase was attempted to the received status. In certain situations, statuses other than Available may be received.

csharp
public void SetListener()
{
    IAP.SetListener((Result result, IAPProduct product, IAPPurchaseDetail purchaseDetail) =>
    {
        if (result.IsSuccessful)
        {
            //구매 성공
        }
        else if (result.IsCanceled)
        {
            //구매 취소
        }
        else if (result.ErrorCode == IAPError.SuccessButUserMissMatchError)
        {
            //구매 성공 (계정 불일치)
            //결제 검증이 완료되지 않은 상태에서 계정 변경 또는 월드 이동 시 발생 가능
        }
        else if (result.ErrorCode == IAPError.PurchasedError)
        {
            //결제 검증 대기 중 - 추후 빌링 서버에서 자동 처리, 푸시로 알림
        }
        else if (result.ErrorCode == IAPError.WaitingError)
        {
            //지급 대기 중 - 추후 자동 처리, 푸시로 알림
        }
        else if (result.ErrorCode == IAPError.MarketError)
        {
            //Android: BillingClient.BillingResponseCode
            //iOS: SKError.Code
        }
    });
}

ErrorCodes

DomainErrorCodeDescription
com.stove.success0Success
com.stove.cancel10Canceled
com.stove.iap40000SuccessButUserMissMatch
com.stove.iap40001Waiting
com.stove.iap40002MarketError (Android: BillingResponseCode / iOS: Payment Failed)
com.stove.iap40006Purchased
com.stove.server10001invalid parameters
com.stove.server10004not exists noti-api
com.stove.server10007is not supported environment
com.stove.server30000verify fail
com.stove.server30006canceled transaction - verify fail
com.stove.server30007revoked transaction - verify fail
com.stove.server30011completed transaction
com.stove.server30012duplicate store receipt
com.stove.server30014failed transaction
com.stove.server30015sandbox transaction (Occurs when a test account is not registered in LIVE)
com.stove.server40001supply server response is 'fail'
com.stove.server40005noti api call fail
com.stove.server40006cash api call fail
com.stove.server40007itembox api call fail



Configuring the Store

Configure the store by querying products from the market. The main fields of the query response, "IAPProduct", are as follows.


IAPProduct Fields

Field NameDescriptionExample
ProductTypeProduct type (inapp/subs)inapp
productIdentifierMarket-registered product ID (passed during purchase request)google_item01
stoveProductIdProduct ID registered in Stove Partnersstove_item01
localizedTitleMarket product nameBattle Shield
localizedDescriptionMarket product descriptionProduct description...
pricePrice (displayed amount)₩1,100
priceCurrencyCodeCurrency codeKRW, JPY, USD
priceAmountMicrosPrice in micros (÷1,000,000 = actual amount)1100000000
ProductStateProduct stateAvailable / Waiting / Purchased
isLimitWhether purchase is limitedfalse
purchaseLimitPurchase limit information (3.1.0 or higher, see table below)-
subscriptionPeriodSubscription period (ISO 8601)P1M
freeTrialPeriodsFree trial period (ISO 8601)P7D

Purchase Limit Information (3.1.0 or higher)

Starting from 3.1.0, the purchase limit quantity based on account, character, and world, along with the quantity purchased so far, are provided for each product. Use this when displaying the available purchase quantity in the store, such as "1/5".

Field NameDescriptionExample
accountPurchasedCountAccount-based purchase quantity1
accountLimitAccount-based purchase limit (0 = no limit)5
characterPurchasedCountCharacter-based purchase quantity0
characterLimitCharacter-based purchase limit (0 = no limit)0
worldPurchasedCountTotal world purchase quantity (sum of all users)120
worldLimitWorld-based purchase limit (0 = no limit)1000
  • Field names follow platform conventions. Android · iOS · Unreal use "purchaseLimit.accountLimit", and Unity uses "PurchaseLimit.AccountLimit".
  • If the limit quantity is "0", there is no limit for that criterion. Even if purchase limit information is not received, all values are returned as "0", and the product list query will still succeed.
  • Purchase quantities are populated only after setting the character and world with "캐릭터 설정(setGameProfile)". If you query before setting them, the limit quantity will be returned, but the purchase quantity will be "0".
  • Quantities are based on the time of the query. Actual purchase availability is re-verified by the server during payment.
  • Existing "isLimit" is also still provided.

📌 Purchase limit information is only provided for games where the Stove-side setting is enabled. Please contact your technical PL to use this feature.

📌 3.1.0 purchase limit information is provided in iOS · Android · Unity · Unreal, and for Android, it is limited to Google Play. This feature is not supported on Huawei or One Store.

Recommendations: Display purchase buttons differently based on the product state.

  • Available: Purchase available state
  • Waiting: Payment pending state (purchase in progress)
  • Purchased: Purchase completed but not yet delivered (handle re-delivery via flush)

csharp
#if UNITY_ANDROID
using Stove.StoveSDK.IAP.Google;
#endif

public void FetchProducts()
{
    IAP.FetchProducts((Result result, List<IAPProduct> products) =>
    {
        if (result.IsSuccessful)
        {
            foreach (IAPProduct product in products)
            {
                IAPProduct.ProductState state = product.State;
                if (state == IAPProduct.ProductState.Available) { /* 구매 가능 */ }
                else if (state == IAPProduct.ProductState.Waiting) { /* 결제 중 */ }
                else if (state == IAPProduct.ProductState.Purchased) { /* flush 필요 */ }
                string localizedTitle = product.LocalizedTitle;
                string price = product.Price;
            }
        }
        else if (result.IsServerError) { /* 빌링 서버 오류 */ }
        else { /* 네트워크 오류 */ }
    });
}

Displaying Purchase Limits (3.1.0 or higher)

In the shop, purchase limits are displayed in the following order.

  1. If the limit quantity is 0, the criteria are not displayed.
  2. Calculate the remaining quantity (제한 수량 - 구매 수량) for each criterion.
  3. If there is no remaining quantity for even one criterion, the purchase button is disabled.
  4. Once the payment is complete, query the product list again to update the figures.
CriterionMeaningDisplay Example
AccountQuantity purchasable with this account1/5 per account
CharacterQuantity purchasable with the current character0/1 per character
WorldLimited quantity shared by all users in the world880 remaining
  • The world purchase quantity is the total for all users. It is recommended to show the remaining quantity rather than your own purchase count.
StatusConditionButton Example
No LimitAll limit quantities are 0Purchase
AvailableRemaining quantity exists for all criteriaPurchase + Limit text
Limit ReachedNo remaining quantity for account or character criteriaPurchase Complete (Disabled)
Sold OutNo remaining quantity for world criterionSold Out (Disabled)
  • Check the product status (ProductState) before the purchase limit. Waiting · Purchased products are handled according to the recommendations above.
  • The product list is queried when entering the shop, changing characters, or completing a payment. Figures are based on the time of the query.
  • The screen display is for informational purposes. After the query, the limit may be reached due to purchases on other devices or by other users; in this case, the server will reject the purchase at the payment stage. If a payment failure is received, query the product list again to refresh the screen.
  • If purchase limit information is not received and all values are 0, only the purchase button is displayed without any limit text.

csharp
using System;
using System.Collections.Generic;
using Stove.StoveSDK;

bool HasLeft(int purchased, int max)
{
    return max == 0 || purchased < max;
}

bool CanPurchase(IAPProduct product)
{
    IAPPurchaseLimit limit = product.PurchaseLimit;
    return product.State == IAPProduct.ProductState.Available
        && HasLeft(limit.AccountPurchasedCount, limit.AccountLimit)
        && HasLeft(limit.CharacterPurchasedCount, limit.CharacterLimit)
        && HasLeft(limit.WorldPurchasedCount, limit.WorldLimit);
}

string LimitText(IAPProduct product)
{
    IAPPurchaseLimit limit = product.PurchaseLimit;
    var texts = new List<string>();
    if (limit.AccountLimit > 0) texts.Add($"계정당 {limit.AccountPurchasedCount}/{limit.AccountLimit}");
    if (limit.CharacterLimit > 0) texts.Add($"캐릭터당 {limit.CharacterPurchasedCount}/{limit.CharacterLimit}");
    if (limit.WorldLimit > 0) texts.Add($"남은 수량 {Math.Max(limit.WorldLimit - limit.WorldPurchasedCount, 0)}");
    return string.Join(" · ", texts);
}

ErrorCodes

DomainErrorCodeDescription
com.stove.success0Success
com.stove.server20000not exists value
com.stove.server21000No content
com.stove.server21001not exists game
com.stove.server21002Not exists marketCode
com.stove.base.network10001NoConnectionError
com.stove.base.network10002TimeoutError



Purchase

Depending on the product's ProductState, it is handled differently. AvailableIf it is , only startPurchase is called, and Purchased is flush handled as a re-provisioning.


csharp
#if UNITY_ANDROID
using Stove.StoveSDK.IAP.Google;
#endif

public void StartPurchase(IAPProduct product)
{
    IAPProduct.ProductState state = product.State;
    if (state == IAPProduct.ProductState.Waiting) { /* 결제 중 - 버튼 비활성화 */ }
    else if (state == IAPProduct.ProductState.Available)
    {
        IAP.StartPurchase(product, (Result result) =>
        {
            if (result.IsSuccessful) { /* 결제 시작됨 */ }
            else if (result.IsServerError)
            {
                if (result.ErrorCode == 93106) { /* 이미 구독 중인 상품 */ }
            }
            else if (result.ErrorCode == Auth.UnauthorizedError) { /* AuthUI.login */ }
            else if (result.ErrorCode == IAPError.InvalidProductError) { /* fetchProducts 결과 사용 */ }
            else { /* 네트워크 오류 */ }
        });
    }
    else if (state == IAPProduct.ProductState.Purchased)
    {
        IAP.Flush(); //재지급 처리
    }
}

ErrorCodes

DomainErrorCodeDescription
com.stove.success0Success
com.stove.auth30002UnauthorizedError
com.stove.iap40003InitializeError
com.stove.iap40004InvalidProduct
com.stove.iap40006PurchasedNeedFlush
com.stove.iap40008ListenerError
com.stove.iap40009InvalidUser
com.stove.iap40010iOS pay country code nil
com.stove.server20005initialize fail on already purchased split product
com.stove.server93102invalid product info
com.stove.server93103is not sales product
com.stove.server93104limit purchase
com.stove.server93106exists purchased subscript product
com.stove.server93107not subscript product
com.stove.server93108product is subscript and limit
com.stove.server93110over limit on purchase of payment amount
com.stove.base.network10001NoConnectionError
com.stove.base.network10002TimeoutError



flush

This is used to process consumption for products that have been paid for but not yet delivered, and to request re-provisioning of products. The processing result is delivered to the listener set in IAP.setListener.


csharp
public void Flush()
{
    IAP.Flush();
    // 결과는 setListener의 콜백으로 전달됨
}

Setting developer payload during payment

When calling for payment, if you set serviceOrderId you can verify it in the payment response.

⚠️ Caution
The payload value is not guaranteed to be delivered 100% in some user refund cases (such as app deletion).
Be careful not to use it as primary information that affects payment delivery.


csharp
string serviceOrderId = "set your developer payload";
IAP.StartPurchase(product, serviceOrderId, null, (Result result) => { });

Querying refund history (data)

Receive the user's market refund history as data only, without a UI. Use this when you need to guide users with refund history to re-purchase directly in the game or restrict their access. To handle this using the UI provided by the SDK, use the Refund History UI(handleVoidedPurchases) below.


csharp
IAP.FetchVoidedPurchases((Result result, List<Dictionary<string, object>> voidedPurchases) =>
{
    if (result.IsSuccessful)
    {
        if (voidedPurchases.Count > 0)
        {
            // 환불 내역이 있으면 재결제 안내 또는 접속 제한 등 게임 정책에 따라 처리
        }
        else
        {
            // 환불 내역 없음 → 게임 진입
        }
    }
    else
    {
        // 조회 실패
        OperationUI.HandleResult(result, (Result operationResult) => { });
    }
});



Refund History UI

Displays the user's market refund history on the screen. If a refund payment is required, it can be processed from this screen.


csharp
#if UNITY_ANDROID
using Stove.StoveSDK.IAP.Google;
#endif

public void HandleVoidedPurchases()
{
    IAP.HandleVoidedPurchases((Result result) =>
    {
        if (result.IsSuccessful)
        {
            /** 게임 진입 가능 **/
        }
        else if (result.IsCanceled)
        {
            if (result.UserInfo != null && result.UserInfo.TryGetValue("userAction", out string userAction))
            {
                if (!string.IsNullOrEmpty(userAction) && userAction.Equals("customerSupport"))
                {
                    ViewUI.CustomerSupport((Result result, Dictionary<string, string> dictionary) =>
                    {
                        HandleVoidedPurchases();
                    });
                    return;
                }
            }
            HandleVoidedPurchases();
        }
        else
        {
            OperationUI.HandleResult(result, (Result operationResult) =>
            {
                if (result.ErrorCode == 40303)
                {
                    Auth.Logout();
                }
            });
        }
    });
}

Required Multi-Character (Multi-Currency) Management Settings

Applicability
Multi-character settings are required if any of the following apply:

  • Games serviced with multiple worlds (character/item distribution per world)
  • Single server but with internal characters requiring character-specific payments/distribution
  • Two or more Partners World settings
  • Using both the Stove secondary currency system and In-App Purchase (IAP) features

Partners (SDK Config) Settings

You must configure the following items in the Partners SDK Config.

  • use_custom_billing_guid = true

Client Tasks - Setting User Unique Identifier

  • Timing: Immediately after creating (initializing) the SDK IAP object, you must set the user who will receive the items (setCustomBillingGUID). Note: Ensure this is set after a world or character has been selected.
  • Method (Standard recommended method when using Stove game character features): Set in the form of a {STOVE_guid}_{STOVE_character_no} combination. Even with this setting, the character_no field is correctly transmitted when requesting distribution from the billing server after payment completion.

Notice (2025.05.15)
For new games, the guide has been changed to a {STOVE_guid}_{STOVE_character_no} combination to flexibly support various features such as 'Account Gifting'. This setting applies only to mobile environments.


csharp
IAP.SetCustomBillingGUID("{STOVE_guid}_{STOVE_character_no}");

iOS Promoted

Integration for promoted in-app purchases within the App Store.

  • Available from iOS 11 and later
  • The purchasePromotion call timing is after initialization and login are complete

Code Example (iOS)

objectivec
#import <SGSIAP/SGSIAP.h>
#import <StoreKit/StoreKit.h>

@interface AppDelegate () <SKPaymentTransactionObserver>
@property (nonatomic) NSString *promotionProductID;
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[SKPaymentQueue defaultQueue] addTransactionObserver:self];
    return YES;
}

- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray<SKPaymentTransaction *> *)transactions
{
}

- (BOOL)paymentQueue:(SKPaymentQueue *)queue shouldAddStorePayment:(SKPayment *)payment forProduct:(SKProduct *)product {
    //프로모션 아이템 정보를 저장
    self.promotionProductID = product.productIdentifier;
    return NO;
}

//프로모션 상품 저장 여부 체크
- (BOOL)isExistPromotion {
    return (self.promotionProductID != nil);
}

//프로모션 상품 결제
- (void)purchasePromotion {
    [SGSIAP fetchProductsWithCompletionHandler:^(SGSResult * _Nonnull result, NSArray<SGSIAPProduct *> * _Nullable products) {
        if ([result isSuccessful]) {
            for (SGSIAPProduct *product in products) {
                if ([product.productIdentifier isEqualToString:self.promotionProductID]) {
                    [SGSIAP startPurchaseWithProduct:product completionHandler:^(SGSResult * _Nonnull result) {
                        if (result.isSuccessful) { /* 결제 성공 */ }
                        else { /* 결제 실패 */ }
                    }];
                    break;
                }
            }
        } else if ([result isServerError]) {
            //빌링 서버 오류
        } else {
            //네트워크 오류
        }
    }];
}

@end

PC IAP

Prerequisites
  • BaseSDK initialization (Base_Initialize) and user login must be completed first. Then, initialize the IAPSDK with IAP_Initialize(shopKey). If you need to specify a parent window, use IAP_InitializeWithWndInfo.
  • The callback runner (Base_RunCallback()) must be called periodically in the game loop for asynchronous callbacks to function.
  • A payment notification reception URL and billing information for each market (Google/Apple/Steam) must be registered in Partners.
  • When using multi-character (multi-currency), set the user identifier first using the game profile setting API.
  • For games distributed via the Steam launcher, Stove authentication must be completed via the external platform integration module (APIModule), PCSDK3 must be running, and the game must directly integrate and initialize the Steamworks SDK. For detailed flow, refer to Steam Payment below.

Development Flow
  1. Initialization: After Base_Initialize is complete, initialize the IAP module with IAP_Initialize(shopKey) (use IAP_InitializeWithWndInfo if a parent window is required).
  2. Terms Agreement Check: Use IAP_FetchTermsAgreement to check if mandatory terms have been agreed to; if not, proceed with the terms agreement flow.
  3. Store Configuration: Retrieve the product list using category inquiry (IAP_FetchShopCategories) and product list inquiry (IAP_FetchProducts) to build the UI.
  4. Purchase Process: Call IAP_StartPurchase / IAP_StartPurchaseEx when selected by the user. Use the operation in StovePCPurchaseOption to determine the payment UI and confirmation method, and webViewMode to determine how the payment window is displayed. (Refer to Purchase Options and Payment Window Display Method below.) Refer to Transferring Product Inquiry Results to Purchase Parameters below for how to map retrieved product information to purchase parameters.
  5. Purchase Confirmation/Verification: After payment is complete, call IAP_ConfirmPurchase for client-side confirmation, and perform secondary verification on the game server using the payment validity check API.
  6. Inventory: Use inventory inquiry (IAP_FetchInventory) if necessary.
  7. Additional Actions: Use IAP_WithdrawGame for the game termination (terms withdrawal) UI, and IAP_CloseAllPopups to close all open payment windows.
  8. Cleanup: Before terminating the game, clean up the IAP module with IAP_UnInitialize() and then call Base_UnInitialize().

Games distributed via Steam Launcher have different steps 4–7. Please refer to Steam Payment below.


Purchase Options and Payment Window Display Methods

IAP_StartPurchaseWhen calling /IAP_StartPurchaseEx, you define two things using StovePCPurchaseOption. operation(SetOperation) determines whether the SDK displays the payment window and whether the SDK handles purchase confirmation on your behalf, while webViewMode(SetWebviewMode) determines whether the payment window displayed by the SDK is drawn as an overlay within the game window or as a separate window. The same webViewMode setting applies to the Terms of Service inquiry(IAP_FetchTermsAgreement)'s StovePCTermsOption and game uninstallation(IAP_WithdrawGame)'s StovePCWithdrawGameOption as well, so the explanation below applies to them too.

Purchase Option (operation)

ValuePayment Window DisplayPurchase Confirmation (ConfirmPurchase)Completion Result Delivery Location
StovePCPurchaseOperation::WITH_WEBVIEW_AND_CONFIRM_RESULT (Recommended)SDK WebViewAutomatically called by SDKIAP_StartPurchase(Ex)'s onFinished callback
StovePCPurchaseOperation::WITH_WEBVIEWSDK WebViewCalled directly by the gameIAP_ConfirmPurchase callback
StovePCPurchaseOperation::DEFAULTNot displayed. The game directly opens the one-time payment URL(oneTimePaymentUrl) received as a resultCalled directly by the gameIAP_ConfirmPurchase callback

ㆍ WITH_WEBVIEW_AND_CONFIRM_RESULT: Since the SDK handles both payment completion detection and purchase confirmation, do not call IAP_ConfirmPurchase separately (doing so will result in duplicate confirmation). The SDK also handles 0-won items internally and delivers them via the same onFinished callback.
ㆍ WITH_WEBVIEW: The SDK displays the payment window but does not notify you of payment completion. onFinished is triggered when the URL is loaded in the payment window, and onDestroy is merely a screen cleanup event, not a payment completion signal. Since the game must call IAP_ConfirmPurchase directly, this is not recommended unless there is a specific reason.
ㆍ DEFAULT: The SDK only creates the order and returns a one-time payment URL. The game is responsible for opening the payment window and calling IAP_ConfirmPurchase. Since the SDK does not display the payment window, SetWebviewMode and SetWebviewRect do not apply, and onDestroy is not called.

DEFAULT Option Usage Sequence

Choose DEFAULT when you need to embed the payment page in a built-in browser (CEF, Unity WebView, etc.) or control the payment window directly according to your game's UI flow. If it is sufficient for the SDK to display the payment window and notify you of the result, WITH_WEBVIEW_AND_CONFIRM_RESULT is simpler.

  1. Create Order: When you call IAP_StartPurchase(Ex), the transaction number(transactionMasterNumber) and one-time payment URL(oneTimePaymentUrl) are returned via onFinished. This point is before payment. Save the transaction number locally in case of abnormal termination, and if a saved number exists upon restart, finish it with IAP_ConfirmPurchase.
  2. Verify 0-won Payment: If purchaseProgress is NOT_NEED_PAYMENT_WINDOW, there is no payment URL and the purchase is already complete. Do not open the window; call IAP_ConfirmPurchase immediately to receive the item list.
  3. Display Payment Window: Open the received URL using your preferred browser component. Since the SDK does not communicate separately with the payment page, there is no need to add integration code to the browser. The payment page may open a new window depending on the payment method, so please allow new windows. The URL is one-time use; call IAP_StartPurchase again to retry.
  4. Confirm Purchase: Once the payment window is closed, call IAP_ConfirmPurchase once using the saved transaction number. Since this is an inquiry API, there are no side effects even if the payment was not made or was canceled. If the first inquiry returns 'unconfirmed', retry only once after 5 seconds; if it is still 'unconfirmed', have the user check again via a "Payment Confirmation" button. Since the user might return to the game without closing the window, always display this button during payment. Do not call the same API repeatedly before the previous callback arrives, as the callback will be overwritten.
  5. Item Distribution: Distribute items only when payment completion is confirmed based on the three-way judgment below.

Reading ConfirmPurchase Results

Callback ResultMeaningGame Action
IsSuccessful() == true and status == truePayment CompleteDistribute items based on purchasedProducts.
IsSuccessful() == true and status == falsePayment Incomplete (Canceled, not yet paid, or not reflected on server)Do not distribute. If immediately after closing the payment window, retry only once after 5 seconds.
IsSuccessful() == falseInquiry Failed (Network, server error, invalid transaction number)Do not distribute. Retry or inform the user. Unapproved orders may come as external_error 22001, which should also be treated as incomplete.

Judging Stove Launcher and Steam Launcher with One Condition

The table above is based on the Stove Launcher flow. In the Steam Launcher flow, the SDK always returns status as false, so if you use the condition that checks IsSuccessful and status together, payments confirmed on Steam will be treated as failures. Since you cannot distinguish the two flows by callback values alone and there is no inquiry API, set a flag when Stove authentication is completed via the External Platform Integration Module and judge in a single function as shown below. If the SDK has a SteamUserId passed during initialization, it automatically processes it as a Steam payment flow; otherwise, it processes it as a Stove payment window flow.

Common Mistakes

  • Distributing items or calling ConfirmPurchase immediately upon receiving onFinished. This point is before payment.
  • Judging payment completion solely by the fact that the payment window closed. Closing is independent of payment status; judge only by the ConfirmPurchase result.
  • Treating ```cpp
    static bool g_isSteamPayment = false; // 외부플랫폼연동모듈(스팀) 인증 경로로 기동했다면 true
    enum class ConfirmOutcome { Failed, Pending, Confirmed };
    ConfirmOutcome JudgeConfirmPurchase(const CallbackResult& callbackResult, bool status)
    {
    if (!callbackResult.GetResult().IsSuccessful())
    return ConfirmOutcome::Failed; // 호출 실패. GetExternalError() 로 원인 확인 (스팀 미승인 22001 포함)
    if (g_isSteamPayment || status)
    return ConfirmOutcome::Confirmed; // 스팀런처 동선은 status 가 항상 false 라 호출 성공 = 확정
    return ConfirmOutcome::Pending; // 스토브런처 동선 미확정. 닫힘 직후면 5초 뒤 1회 재조회
    }
    text
csharp
    static bool g_isSteamPayment = false;   // 외부플랫폼연동모듈(스팀) 인증 경로로 기동했다면 true

    enum ConfirmOutcome { Failed, Pending, Confirmed }

    static ConfirmOutcome JudgeConfirmPurchase(CallbackResult callbackResult, bool status)
    {
        if (!callbackResult.result.IsSuccessful())
            return ConfirmOutcome.Failed;      // 호출 실패. externalError 로 원인 확인 (스팀 미승인 22001 포함)

        if (g_isSteamPayment || status)
            return ConfirmOutcome.Confirmed;   // 스팀런처 동선은 status 가 항상 false 라 호출 성공 = 확정

        return ConfirmOutcome.Pending;         // 스토브런처 동선 미확정. 닫힘 직후면 5초 뒤 1회 재조회
    }

status == false as an error and displaying a failure message to the user. In most cases, this is a normal flow where the user closed the window without paying.

Opening in an External Browser

If you do not want to use a built-in browser, you can open the payment URL received via DEFAULT in the user's default browser (ShellExecute, for Unity Application.OpenURL). The SDK does not attach cookies, headers, or tokens to the URL, so the same payment page opens in any browser. Base_OpenExternalUrl is wrapped in the Stove SSO login address, so use it only when the payment page requires a Stove login session in the browser. You need to verify if the one-time payment URL is passed correctly after [확인 필요] SSO transit.

  • External browsers do not pass close events to the game. Instead of "call when window closes," use game window activation return (for Win32, WM_ACTIVATEAPP, Unity calls the same verification function in both OnApplicationFocus) and the "Confirm Payment" button, and use an in-progress flag to prevent overlapping calls.
  • Do not delete the transaction number immediately even if you receive status == false in the first query. The user may still be in the middle of payment in the browser. Only clear it when payment is confirmed as complete, and clean it up if the user chooses to cancel or starts a new payment. The server will clean up incomplete orders on its own.
  • Exclusive fullscreen games may be minimized the moment they switch to the browser. Windowed or borderless fullscreen mode is recommended during payment.

Steam distribution games always behave like DEFAULT regardless of the operation value, but since the payment window is displayed by the Steam overlay, the "Display Payment Window" step in the description above does not apply. Please refer to the Steam Payment section.

Payment Window Display Method (webViewMode)

ValueDisplay MethodFeatures
WebViewMode::INTERNALDraws as a child window of the main game window, overlapping the game screenYou can specify the position and size (SetWebviewRect(x, y, width, height), in pixels). You must pass the game window handle to IAP_InitializeWithWndInfo during initialization, and if a child window cannot be created, it will operate as EXTERNAL
WebViewMode::EXTERNALDraws as a separate window independent of the game windowSince it covers the entire screen, it is not affected by the display state of the game window

!warning
Exclusive Fullscreen (FSE) games cannot use INTERNAL. Since INTERNAL draws the window overlapping the game screen, the payment window will not be drawn in Exclusive Fullscreen mode. EXTERNAL displays the payment window even in Exclusive Fullscreen mode, but there is an issue where the game screen is minimized as the separate window comes to the front. Therefore, for games using Exclusive Fullscreen, it is recommended to switch the game screen to Borderless Windowed Fullscreen when displaying the payment window.


Moving Product Query Results to Purchase Parameters

Since the IAP_FetchProducts received in the product list query (StovePCProduct) callback and the IAP_StartPurchase included in the purchase request (StovePCOrderProduct) are different structures, you cannot pass the queried product as is and must move the necessary values. The values to move are the following three:

StovePCOrderProduct (Purchase Request)Value to RetrieveDescription
SetProductIdStovePCProduct::GetProductId()This is the platform product ID. Move it as is.
SetSalePriceStovePCProduct::GetSalePrice()This is the sale price for payment. Since the server compares this value with the actual sale price, move it as is. If you enter the list price (GetPrice()) or display price (GetDisplaySalePrice(), etc.), the purchase may be rejected due to a price mismatch.
SetQuantityPurchase quantity selected by the userStovePCProduct::GetQuantity() is the quantity of items provided when purchasing this product once, not the purchase quantity. Do not copy it; enter the quantity selected by the user (usually 1).

Since the time of pressing the purchase button is later than the query callback, do not use the array received as a callback argument outside the callback; copy the product ID and sale price into the game's store model inside the callback, and create the StovePCOrderProduct when purchasing. Since the sale price can change due to discount periods, etc., you must use the value from the query result shown on the screen just before purchase. The IAP_FetchProductsEx received via StovePCProductEx also provides the same getter, so move it using the same method. The Game:: / Game. call and ShopItem in the example are pseudo-code implemented by the developer.

=== "Native (Unreal)"
cpp
// Store model — Values copied in the query callback
struct ShopItem
{
int64_t productId;
double salePrice;
};

// (1) Product list query callback — Copy only the values needed for purchase
IAP_FetchProducts(&fetchParams,
[](CallbackResult callbackResult, StovePCProduct* products, uint32_t productsSize)
{
if (!callbackResult.GetResult().IsSuccessful())
return;

for (uint32_t i = 0; i < productsSize; ++i)
{
ShopItem item;
item.productId = productsi.GetProductId();
item.salePrice = productsi.GetSalePrice(); // Sale price for payment (Not GetPrice() or GetDisplaySalePrice())
Game::Shop::Add(item);
}
});

// (2) Buy button — Create an order item with the stored value and the quantity selected by the user
void OnBuyClicked(const ShopItem& item, int32_t count)
{
StovePCOrderProduct orderProduct;
orderProduct.SetProductId(item.productId);
orderProduct.SetSalePrice(item.salePrice);
orderProduct.SetQuantity(count); // Purchase quantity selected by the user. Do not enter StovePCProduct::GetQuantity()

StovePCStartPurchaseParam params;
params.CreateOrderProduct(1);
params.SetOrderProduct(0, &orderProduct);
// Subsequent option settings and IAP_StartPurchaseEx calls are the same as (1) in the sample code below.
}

text
=== "Unity"
```csharp
// Shop model — Values copied from the query callback
public struct ShopItem
{
    public long   productId;
    public double salePrice;
}

// (1) Product list query callback — Copy only the values required for purchase
IAP_FetchProducts(fetchParams, (callbackResult, products) =>
{
    if (!callbackResult.result.IsSuccessful())
        return;

    foreach (StovePCProduct product in products)
    {
        Game.Shop.Add(new ShopItem
        {
            productId = product.productId,
            salePrice = product.salePrice,   // Sale price for payment (Not price or displaySalePrice)
        });
    }
});

// (2) Buy button — Create an order item with the stored value and the quantity selected by the user
void OnBuyClicked(ShopItem item, int count)
{
    var orderProduct = new StovePCOrderProduct
    {
        productId = item.productId,
        salePrice = item.salePrice,
        quantity  = count,   // Purchase quantity selected by the user. Do not enter StovePCProduct.quantity
    };

    var param = new StovePCStartPurchaseParam
    {
        products     = new[] { orderProduct },
        productsSize = 1,
    };
    // Subsequent option settings and IAP_StartPurchaseEx calls are the same as (1) in the *sample code* below.
}


<br />

##### Steam Payment

This is the payment flow for games distributed and executed via the Steam launcher. If you are distributing only via the Stove launcher, you can skip this section and follow the flow above.

This flow assumes that the game has **completed Stove authentication via the External Platform Integration Module (APIModule) and that the PCSDK3 is running**. Module integration and Steam game terms of service agreement are covered in the Steam Integration Guide; this section only explains the payment part thereafter.

`IAP_StartPurchase`There are no parameters or options to distinguish between the Steam launcher flow and the Stove launcher flow. There is also no place for the developer to set whether the payment window (Stove launcher feature) or the Steam overlay appears when executed based on Steam. The criteria the SDK uses to select the flow is the Steam user ID (SteamUserId) passed during the initialization of the external platform integration module. If this value exists, it is automatically processed as the Steam payment flow; if not (including Stove launcher execution), it is processed as the Stove payment window flow, and there is no API to query the current flow. If you support both the Stove launcher and the Steam launcher, set a flag at the time of authentication via the external platform integration module, and `IAP_ConfirmPurchase` read the result as the common judgment in *To determine the Stove launcher and Steam launcher with one condition* above.

```mermaid
flowchart TD
classDef shop fill:#EDEDE9,stroke:#8D99AE,color:#2B2D42
classDef pay  fill:#EDE7F6,stroke:#7E57C2,color:#311B92
classDef ok   fill:#D5F5E3,stroke:#27AE60,color:#145A32
classDef no   fill:#FDECEA,stroke:#C0392B,color:#7B241C

C[IAP_FetchShopCategories<br/>샵 카테고리 조회] --> P[IAP_FetchProducts<br/>카테고리별 상품 목록 조회]
P --> SP[IAP_StartPurchase<br/>productId · salePrice · quantity]

SP --> CB[StartPurchase 콜백<br/>거래 마스터 번호 확보]
SP --> OV[스팀 결제 오버레이 노출<br/>스팀런처가 게임에 주입]

CB --> HOLD[거래 마스터 번호 보관]
OV --> Q{사용자 승인?}
Q -->|취소·실패| X([결제 종료<br/>지급 없음])
Q -->|승인| MT[MicroTxnAuthorizationResponse_t<br/>Steamworks 콜백]
HOLD -. 거래 마스터 번호 .-> MT

MT --> CF[IAP_ConfirmPurchase<br/>보관한 번호로 구매 확정]
CF --> INV[IAP_FetchInventory<br/>지급 아이템 확인]

class C,P shop
class SP,CB,OV,MT pay
class CF,INV ok
class X no

Flow

  1. Shop Configuration: IAP_FetchShopCategories for categories, IAP_FetchProducts to query the product list and configure the shop UI. Up to this point, it is the same as the basic flow.
  2. Start Purchase: When the user selects a product, call IAP_StartPurchase. Fill in only the product information (productId·salePrice·quantity) and leave StovePCPurchaseOption as the default value.
  3. Two things happen simultaneously: ① The Transaction Master Number (IAP_StartPurchase) arrives via the transactionMasterNumber callback, and ② the Steam launcher displays the Steam Payment Overlay over the game. The order of these two actions is not guaranteed, so keep the transaction master number received in the callback stored in a variable.
  4. User Payment: The user approves or cancels the purchase in the overlay. Since this screen is drawn by Steam, there is no UI for the developer to create.
  5. Receive Result: The approval/cancellation result arrives not via the SDK, but via the MicroTxnAuthorizationResponse_t callback of Steamworks. Callback registration and processing are in the Steamworks SDK area that the game has integrated.
  6. Confirm Purchase: If approved, call IAP_ConfirmPurchase with the stored transaction master number. There is no automatic confirmation in the Steam flow, so if you skip this call, the item will not be delivered. Orders that end in cancellation or non-approval are settled by the backend as payment cancellations even if you do not call this, but if you do not receive a result callback, check the final status with this call.
  7. Check Delivery: Check the delivered items with IAP_FetchInventory.

For the actual implementation code, refer to Sample Code → Steam Payment (Steam Launcher Distributed Game) below. The (1)~(3) operation examples in the same Sample Code are for the Stove payment window flow and do not apply to the Steam flow.


Payment Overlay Screen

When the user starts a purchase, the Steam launcher displays a purchase approval screen like the one below over the game. The product name, quantity, and amount are composed by the backend delivering the product information registered in Stove to Steam.


Differences from Basic PC Payment

  • StovePCPurchaseOption is not applied. No matter what value is entered, it behaves like DEFAULT, and the Steam overlay handles the payment window.
  • The payment completion signal comes not via the IAP_StartPurchase callback, but via the MicroTxnAuthorizationResponse_t callback of Steamworks. You must run both the SDK callback runner (Base_RunCallback()) and the Steamworks callback pump (SteamAPI_RunCallbacks()).
  • There is no SDK automatic confirmation. Even if approved in the Steam overlay, if you do not call IAP_ConfirmPurchase, the item will not be delivered.
  • Among the payment API callback values, only the Transaction Master Number (transactionMasterNumber) is valid. The payment URL·purchaseProgress·purchased product array·billing information·status are returned as default values, so do not refer to them; judge only by CallbackResult. If successful, the payment is confirmed and the item has been delivered. If it is a failure and externalError is 22001, it means the Steam transaction was not approved (cancellation, pending approval, expired), so process it as a cancellation. If it is a failure and the result code is 249 (NETWORK_TRANSPORT_ERROR), call again only after receiving the callback of the previous call after network guidance. Other failures are server or SDK errors.
  • If IAP_StartPurchase fails with externalError 21107, there is an incomplete previous Steam transaction remaining. Do not retry; guide the user with "A previous payment is in progress. Please complete or cancel it in the Steam overlay," and if there is a previous transaction master number, call IAP_ConfirmPurchase once to settle the status.
  • Terms of service agreement (IAP_FetchTermsAgreement) is not used. Steam game terms of service agreement is handled in the external platform integration module flow. Game withdrawal (IAP_WithdrawGame) is not supported.

!warning
Steam callback may not arrive
Although this is an issue that occurs in the Steamworks SDK implementation rather than the STOVE PCSDK, we provide this guidance together because payment waiting can continue indefinitely. If the user closes the payment window while the network is disconnected during payment, GameOverlayActivated_t arrives, but MicroTxnAuthorizationResponse_t does not.
ㆍ If GameOverlayActivated_t of m_bActive arrives as 0 while waiting for payment, and MicroTxnAuthorizationResponse_t does not arrive within 3 to 5 seconds from the last closing time, call IAP_ConfirmPurchase with the stored transaction master number to confirm the final status. In the case of a normal cancellation, the cancellation confirmation dialog reopens after the payment window is closed (m_bActive = 1) and the callback arrives about 2 seconds after it is closed, so if the overlay reopens, stop the grace period and measure the grace period again every time it closes.
ㆍ While waiting for payment SteamServersDisconnected_tIf you receive , call immediately without any grace period when the overlay closes.IAP_ConfirmPurchaseUsers who have turned off the overlay (ISteamUtils::IsOverlayEnabled()is false) will not receive , so please provide a button on the payment waiting screen that allows them to check or cancel directly.GameOverlayActivated_t> ㆍ Do not ignore that arrives late after the wait is over, and call .MicroTxnAuthorizationResponse_tThis call goes to the Stove server, so it can be made regardless of the Steam connection status, and the final decision should always be based on the result of this call.IAP_ConfirmPurchase
##### Troubleshooting| Situation | Cause | Solution |
|---|---|---|
| The IAP function does not work immediately after entering the game | BaseSDK initialization (Base_Initialize) or user login has not been completed when the IAP API was called. | Base_Initialize After completion, you must initialize the IAPSDK with IAP_Initialize and call the IAP API after finishing the login. |
| Payment started, but a "Terms of Service not agreed" response is received | The user has not agreed to the Stove payment terms, so payment is blocked. This often happens with new users or immediately after terms are updated. | You must first check if the terms have been agreed to using the Terms Agreement Inquiry API (IAP_FetchTermsAgreement), and if mandatory terms have not been agreed to, you must display the terms agreement popup. There is no issue if you make the user return to the payment flow after completing the agreement. |
| Product inquiry returns an empty product list | Products have not been registered in Partners yet, or they are registered but the Market Key (Product ID) does not match the value being used in the game. This often happens when managing different product IDs for each build. | You must check the product registration status and Market Key in the Partners Billing Console, and verify that the game client is sending the same product ID. If product IDs are separated by environment (Dev/Stage/Live), there is no issue if you check that they match the build environment. |
| The payment window suddenly closes during payment | If a new IAP API is called, the existing payment/terms window will be closed collectively. This is an intentional behavior to prevent two payment flows from being displayed at the same time. | You must prevent additional calls from the game side when starting a payment so that only one IAP flow proceeds at a time. There is no issue if you disable the payment button until the payment completion callback is received. |
| The payment result callback is not called | If the callback runner (Base_RunCallback()) is not called in the game main loop, the payment result event will not be delivered to the game. | You must call the callback runner every frame or at regular intervals in the main loop. There is no issue if you check that it is being called in the same way as the general game loop during payment. |
| Payment was successful, but the item was not delivered in-game and an 50052 (item delivery failure) error is recorded in Stove | Payment is completed through: Stove → Game Server Payment Notification (Webhook) transmission → Game Server response received → Delivery processing. If the game server notification URL is not registered, the path is incorrect, or the game server response is missing, Stove determines the notification transmission failed, records it as an 50052 error, and delivery is omitted. | You must check that the payment notification URL is correctly registered in the Partners Billing settings, and implement the game server to return a normal response synchronously immediately after receiving the notification. If you check the notification URL and server response first, you can prevent the 50052 error from occurring. |
| In a multi-character game, the item is delivered to a different character | If the current character's identifier (character_no) is not set with the Game Profile Settings API before entering payment, the Stove server cannot know which character to deliver to. | You must call the Game Profile Settings API immediately after character selection to update the current character in the SDK. If it is a game with a character change flow, there is no issue if you call it again at each change point. |
| The Steam payment overlay does not appear | The Steamworks SDK is not initialized, the in-game overlay is disabled in the Steam client, or the Steam market information registered in Partners is different from the actual app. | You must first check the Steamworks SDK initialization and the Steam client's overlay settings, and compare the Steam market information registered in Partners Billing with the actual app to ensure there is no issue. |
| Payment was approved in the Steam overlay, but the game does not respond | The Steamworks callback pump (SteamAPI_RunCallbacks()) is not running, so the MicroTxnAuthorizationResponse_t was not delivered to the game. | You must call SteamAPI_RunCallbacks() in the game loop. It is separate from the SDK callback runner (Base_RunCallback()), so there is no issue if you check that both are running. |
| Steam payment was successful, but the item was not delivered | There is no automatic SDK purchase confirmation in the Steam flow, but you did not call IAP_ConfirmPurchase. | MicroTxnAuthorizationResponse_t After receiving the approval result from , you must call IAP_ConfirmPurchase. |
| Trying to confirm the purchase, but there is no transaction master number | IAP_StartPurchase The order of the callback and Steam overlay exposure is not guaranteed, but you did not store the transaction master number received in the callback. | IAP_StartPurchase Store the transaction master number in a variable in the callback, and there is no issue if you retrieve it at the time of the Steamworks callback. |
| The game freezes if you cancel after the network is disconnected and restored while the Steam payment overlay is open | Steamworks did not deliver MicroTxnAuthorizationResponse_t, but the game is waiting only for this callback. | GameOverlayActivated_t Detect overlay closing with , call IAP_ConfirmPurchase, and if externalError is 22001, there is no issue if you process it as a cancellation. |
| IAP_StartPurchase fails with externalError 21107 | There is an incomplete previous Steam transaction remaining. | Guide the user to complete or cancel the previous transaction in the Steam overlay, and call IAP_ConfirmPurchase with the previous transaction master number to clear the state, and there is no issue.

!info
Use the Ex version if you need a payment termination event
IAP_StartPurchase, IAP_StartPayment, etc., only deliver the payment start result. If you need to resume the game flow when the popup closes, call the Ex version (IAP_StartPurchaseEx, IAP_StartPaymentEx, IAP_FetchTermsAgreementEx, IAP_FetchProductsEx) to receive the termination event.

!warning
Payment validation is performed on the game server
Client-side purchase confirmation (IAP_ConfirmPurchase) alone does not guarantee protection against forgery or tampering. The game server must perform secondary verification with the Stove Payment Validation API after receiving the payment notification before granting currency/items.


Sample Code

We provide examples by dividing each function into units. The entire payment flow proceeds in the order of Initialization/Terms → Store Configuration → Purchase → Validation → Inventory. The Game:: / Game. calls in the examples are pseudo-functions implemented by the developer.

Initialization and Termination

Base_Initialize After completion, initialize the IAPSDK with IAP_Initialize(shopKey) (if a parent window is needed, IAP_InitializeWithWndInfo). Upon termination, call IAP_UnInitialize and then clean up with Base_UnInitialize.

=== "Native (Unreal)"

cpp
#include "IAPSDK.h"
using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;
using namespace Stove::PCSDK::IAP;

// 초기화 — Base_Initialize 완료 이후 호출합니다. 부모 창 지정이 필요하면 IAP_InitializeWithWndInfo(shopKey, hwnd)
auto initResult = IAP_Initialize(L"YOUR_SHOP_KEY");
if (!initResult.IsSuccessful())
{
    // 초기화 실패 시 로직을 구현해 주세요.
    return;
}

// 종료 — IAP_UnInitialize 후 Base_UnInitialize 순서로 정리합니다.
IAP_UnInitialize();

=== "Unity"

csharp
using static Stove.PCSDK.Base;
using static Stove.PCSDK.IAP;

// 초기화 — Base_Initialize 완료 이후 호출합니다. 부모 창 지정이 필요하면 IAP_InitializeWithWndInfo(shopKey, hwnd)
Result initResult = IAP_Initialize("YOUR_SHOP_KEY");
if (!initResult.IsSuccessful())
{
    // 초기화 실패 시 로직을 구현해 주세요.
    return;
}

// 종료 — IAP_UnInitialize 후 Base_UnInitialize 순서로 정리합니다.
IAP_UnInitialize();

Terms Agreement

After initialization, first check if mandatory terms have been agreed to with IAP_FetchTermsAgreement. If not agreed, display the terms agreement flow (provided URL or SDK webview).

=== "Native (Unreal)"

cpp
StovePCTermsOption termsOption;
termsOption.SetOperation(StovePCTermsOperation::WITH_WEBVIEW);
termsOption.SetWebviewMode(Base::WebViewMode::INTERNAL);
termsOption.SetWebviewRect(0, 0, 800, 600);
IAP_FetchTermsAgreement(&termsOption,
    [](CallbackResult callbackResult, bool agreed, const wchar_t* url)
    {
        if (callbackResult.GetResult().IsSuccessful() && !agreed)
        {
            // 약관 동의 흐름을 노출해 주세요.
        }
    });

=== "Unity"

csharp
var termsOption = new StovePCTermsOption
{
    operation = StovePCTermsOperation.WITH_WEBVIEW,
    webviewMode = WebViewMode.INTERNAL,
    webviewPosX = 0, webviewPosY = 0, webviewWidth = 800, webviewHeight = 600,
};
IAP_FetchTermsAgreement(termsOption,
    (callbackResult, agreed, url) =>
    {
        if (callbackResult.result.IsSuccessful() && !agreed)
        {
            // 약관 동의 흐름을 노출해 주세요.
        }
    });

Store Configuration

Configure the UI by retrieving store tabs with Category Inquiry (IAP_FetchShopCategories) and item lists for each category with Product List Inquiry (IAP_FetchProducts). If you pass an empty value for the category ID, it will be queried across the entire range.

=== "Native (Unreal)"

cpp
// 1) 카테고리 조회
IAP_FetchShopCategories(
    [](CallbackResult callbackResult, StovePCShopCategory* categories, uint32_t categoriesSize)
    {
        if (callbackResult.GetResult().IsSuccessful())
        {
            // categories[0..categoriesSize) 로 상점 탭 UI 구성
        }
    });

// 2) 상품 목록 조회
StovePCFetchProductParam fetchParams;
fetchParams.SetCategoryId(L"");   // 빈 값이면 전체 카테고리
fetchParams.SetPageNumber(1);
fetchParams.SetPageSize(20);
IAP_FetchProducts(&fetchParams,
    [](CallbackResult callbackResult, StovePCProduct* products, uint32_t productsSize)
    {
        if (callbackResult.GetResult().IsSuccessful())
        {
            // products[0..productsSize) 로 상점 UI 구성
        }
    });

=== "Unity"

csharp
// 1) 카테고리 조회
IAP_FetchShopCategories((callbackResult, shopCategories) =>
{
    if (callbackResult.result.IsSuccessful())
    {
        // shopCategories 로 상점 탭 UI 구성
    }
});

// 2) 상품 목록 조회
var fetchParams = new StovePCFetchProductParam
{
    categoryId = "",   // 빈 값이면 전체 카테고리
    pageNumber = 1,
    pageSize = 20,
};
IAP_FetchProducts(fetchParams, (callbackResult, products) =>
{
    if (callbackResult.result.IsSuccessful())
    {
        // products 로 상점 UI 구성
    }
});
```**In-game Item Purchase** Purchase starts with `IAP_StartPurchase`.`IAP_StartPurchaseEx` (1) below is the recommended example, while (2) and (3) show only the parts that differ from (1). For the operating principles and judgment criteria, please refer to *Purchase Options and Payment Window Display Method* above. **(1) WITH_WEBVIEW_AND_CONFIRM_RESULT — Display Payment Window + Automatic Purchase Verification (Recommended)** The SDK handles the payment window display, payment completion detection, and purchase confirmation, then delivers the result via onFinished. Do not call `IAP_ConfirmPurchase` directly, as it will cause duplicate confirmation. === "Native (Unreal)" cpp #include "IAPSDK.h" using namespace Stove::PCSDK; using namespace Stove::PCSDK::Base; using namespace Stove::PCSDK::IAP;     void IAP_StartPurchase_WITH_WEBVIEW_AND_CONFIRM_RESULT_Example()
{
    // (1) Product configuration — In-game item information selected by the user
    StovePCOrderProduct product1; product1.SetProductId(123); product1.SetSalePrice(1000); product1.SetQuantity(3);
    StovePCOrderProduct product2; product2.SetProductId(456); product2.SetSalePrice(5000); product2.SetQuantity(2);

    StovePCStartPurchaseParam params;
    params.CreateOrderProduct(2);            // Create internal array for the number of ordered products
    params.SetOrderProduct(0, &product1);
    params.SetOrderProduct(1, &product2);

    // (2) Options — SDK payment window + automatic confirmation. SetWebviewRect(x, y, width, height), center is (-1, -1)
    StovePCPurchaseOption option;
    option.SetOperation(StovePCPurchaseOperation::WITH_WEBVIEW_AND_CONFIRM_RESULT);
    option.SetWebviewMode(Base::WebViewMode::INTERNAL);
    option.SetWebviewRect(0, 0, 420, 700);
    params.SetPurchaseOption(option);

    Game::ShopUI::SetPurchaseButtonEnabled(false);   // Prevent duplicate clicks while payment is in progress

    // (3) Start payment — Use Ex version to receive payment window closure (onDestroy)
    IAP_StartPurchaseEx(&params,
        // onFinished: Purchase completion processing point called once after the SDK finishes ConfirmPurchase
        [](CallbackResult callbackResult, StovePCPurchaseResult purchaseResult)
        {
            if (!callbackResult.GetResult().IsSuccessful())
            {
                // Payment failed/cancelled. If WEBVIEW_CLOSED_BEFORE_PURCHASE, it is a cancellation where the user closed the window before payment (not an error),
                // otherwise, it is a payment window entry failure, parameter error, or network/server error. In any case, no items are granted.
                return;
            }

            if (!purchaseResult.IsPurchased())
            {
                // The call was successful but the server did not confirm payment completion (rare). Do not grant items and proceed with re-inquiry or customer support.
                return;
            }

            // Purchase complete — Grant items only here. Since transactionMasterNumber is unique for every transaction, use it as a key to prevent duplicate granting.
            for (uint32_t i = 0; i < purchaseResult.GetPurchasedProductCount(); ++i)
            {
                const StovePCPurchasedProduct* product = purchaseResult.GetPurchasedProduct(i);
                int64_t productId = product->GetProductId();          // Platform product ID
                int64_t detailNo  = product->GetTransactionDetailNumber();   // Purchase detail number
                // Process granting for each purchased item
            }
            for (uint32_t i = 0; i < purchaseResult.GetChargeInfoCount(); ++i)
            {
                const StovePCChargeInfo* charge = purchaseResult.GetChargeInfo(i);
                int32_t type     = charge->GetChargeType();        // 98: STOVE Cash, 99: Points, others: PG payment method
                double deductVal = charge->GetChargeDeductVal();   // Payment price
                // Receipt display, settlement logging, etc.
            }
        },
        // onDestroy: When the payment window is closed. For UI cleanup only (completion judgment and granting are in onFinished)
        [](CallbackResult callbackResult)
        {
            Game::ShopUI::SetPurchaseButtonEnabled(true);
        });
}

=== "Unity"

csharp
using static Stove.PCSDK.IAP;
using static Stove.PCSDK.Base;

public static class IAPWithWebviewAndConfirmResultExample
{
    public static void Run()
    {
        // (1) Product configuration — In-game item information selected by the user
        var products = new StovePCOrderProduct[]
        {
            new StovePCOrderProduct { productId = 123, salePrice = 1000, quantity = 3 },
            new StovePCOrderProduct { productId = 456, salePrice = 5000, quantity = 2 },
        };

        // (2) Options — SDK payment window + automatic confirmation. Webview position/size, center is (-1, -1)
        var option = new StovePCPurchaseOption
        {
            operation = StovePCPurchaseOperation.WITH_WEBVIEW_AND_CONFIRM_RESULT,
            webviewMode = WebViewMode.INTERNAL,
            webviewPosX = 0, webviewPosY = 0, webviewWidth = 420, webviewHeight = 700,
        };

        var param = new StovePCStartPurchaseParam
        {
            products = products,
            productsSize = (uint)products.Length,
            option = option,
        };

        Game.ShopUI.SetPurchaseButtonEnabled(false);   // Prevent duplicate clicks while payment is in progress

        // (3) Start payment — Use Ex version to receive payment window closure (onDestroy)
        IAP_StartPurchaseEx(param,
            // onFinished: Purchase completion processing point called once after the SDK finishes ConfirmPurchase
            (callbackResult, purchaseResult) =>
            {
                if (!callbackResult.result.IsSuccessful())
                {
                    // Payment failed/cancelled. If WEBVIEW_CLOSED_BEFORE_PURCHASE, it is a cancellation where the user closed the window before payment (not an error),
                    // otherwise, it is a payment window entry failure, parameter error, or network/server error. In any case, no items are granted.
                    return;
                }

                if (!purchaseResult.purchased)
                {
                    // The call was successful but the server did not confirm payment completion (rare). Do not grant items and proceed with re-inquiry or customer support.
                    return;
                }

                // Purchase complete — granted only here. Since transactionMasterNumber is unique for every transaction, it is used as a key to prevent duplicate granting.
                foreach (var product in purchaseResult.purchasedProducts)
                {
                    long productId = product.productId;                 // Platform product ID
                    long detailNo  = product.transactionDetailNumber;   // Purchase detail number
                    // Process granting for each purchased item
                }
                foreach (var charge in purchaseResult.chargeInfos)
                {
                    int    type      = charge.chargeType;        // 98: STOVE Cash, 99: Points, Others: PG payment method
                    double deductVal = charge.chargeDeductVal;   // Payment price
                    // Receipt display, settlement logging, etc.
                }
            },
            // onDestroy: When the payment window is closed. For UI cleanup only (completion judgment and granting are in onFinished)
            (callbackResult) =>
            {
                Game.ShopUI.SetPurchaseButtonEnabled(true);
            });
    }
}

(2) DEFAULT — 게임이 결제창을 직접 띄우는 방식

(1)과 달라지는 부분만 보여 줘요. 옵션은 DEFAULT만 지정하고(webview 설정 무의미), onFinished는 결제 URL 발급 시점이라 구매 완료가 아니며, 게임이 띄운 결제창이 닫힐 때 IAP_ConfirmPurchase를 호출해요. onDestroy는 호출되지 않으니 빈 핸들러를 넘겨요. 외부 브라우저로 열 때의 차이는 위 외부 브라우저로 열 때 를 참고하세요.

=== "Native (Unreal)"

cpp
StovePCPurchaseOption option;
option.SetOperation(StovePCPurchaseOperation::DEFAULT);
params.SetPurchaseOption(option);

IAP_StartPurchaseEx(&params,
    // onFinished: Point when payment URL is issued (not purchase completion)
    [](CallbackResult callbackResult, StovePCPurchaseResult purchaseResult)
    {
        if (!callbackResult.GetResult().IsSuccessful())
            return;   // Order creation failed. Terminate after notification

        int64_t txnNo = purchaseResult.GetTransactionMasterNumber();
        Game::SavePendingTransaction(txnNo);   // Store transaction number (local storage recommended to prepare for abnormal termination)

        if (purchaseResult.GetPurchaseProgress() == PurchaseProgress::NOT_NEED_PAYMENT_WINDOW)
        {
            IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);   // 0-won payment: Confirm immediately without a window
            return;
        }

        Game::OpenOwnPaymentPage(purchaseResult.GetOneTimePaymentUrl(), txnNo);   // Game displays payment window
    },
    [](CallbackResult callbackResult) {});   // onDestroy: DEFAULT is not called as there is no SDK payment window

// Called when the payment window displayed by the game is closed. If unconfirmed, re-query once after 5 seconds
void Game_ConfirmOwnPurchase()
{
    int64_t txnNo = Game::PeekPendingTransaction();
    if (txnNo != 0)
        IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);
}

// Purchase confirmation result — The judgment is the same as JudgeConfirmPurchase above
void OnConfirmPurchase(CallbackResult callbackResult, bool status,
                       StovePCPurchasedProduct* purchasedProducts, uint32_t purchasedProductSize,
                       StovePCChargeInfo* chargeInfos, uint32_t chargeInfoSize)
{
    switch (JudgeConfirmPurchase(callbackResult, status))
    {
    case ConfirmOutcome::Confirmed: Game::ClearPendingTransaction(); /* Provide items using purchasedProducts */ break;
    case ConfirmOutcome::Pending:   /* Do not provide. Keep transaction number, re-query or show payment confirmation button */   break;
    case ConfirmOutcome::Failed:    /* Do not provide. Show failure notice */                                   break;
    }
}

=== "Unity"

csharp
var param = new StovePCStartPurchaseParam
{
    products = products,
    productsSize = (uint)products.Length,
    option = new StovePCPurchaseOption { operation = StovePCPurchaseOperation.DEFAULT },
};

IAP_StartPurchaseEx(param,
    // onFinished: Point when payment URL is issued (not purchase completion)
    (callbackResult, purchaseResult) =>
    {
        if (!callbackResult.result.IsSuccessful())
            return;   // Order creation failed. Show notice and terminate

        long txnNo = purchaseResult.transactionMasterNumber;
        Game.SavePendingTransaction(txnNo);   // Keep transaction number (local storage recommended for unexpected termination)

        if (purchaseResult.purchaseProgress == PurchaseProgress.NOT_NEED_PAYMENT_WINDOW)
        {
            IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);   // 0-won payment: Confirm immediately without window
            return;
        }

        Game.OpenOwnPaymentPage(purchaseResult.oneTimePaymentUrl, txnNo);   // Game displays payment window
    },
    (callbackResult) => { });   // onDestroy: DEFAULT is not called as there is no SDK payment window

// Called when the payment window displayed by the game is closed. If unconfirmed, re-query once after 5 seconds
void ConfirmOwnPurchase()
{
    long txnNo = Game.PeekPendingTransaction();
    if (txnNo != 0)
        IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);
}

// Purchase confirmation result — The judgment is the same as JudgeConfirmPurchase above
void OnConfirmPurchase(CallbackResult callbackResult, bool status, StovePCPurchasedProduct[] purchasedProducts, StovePCChargeInfo[] chargeInfos)
{
    switch (JudgeConfirmPurchase(callbackResult, status))
    {
        case ConfirmOutcome.Confirmed: Game.ClearPendingTransaction(); /* Provide items using purchasedProducts */ break;
        case ConfirmOutcome.Pending:   /* Do not provide. Keep transaction number, re-query or show payment confirmation button */  break;
        case ConfirmOutcome.Failed:    /* Do not provide. Show failure notice */                                  break;
    }
}

(3) WITH_WEBVIEW — 결제창 표시 + 구매 검증 수동

(2)와 같은 흐름에서 결제창만 SDK가 띄워요. onFinished는 결제창에 URL이 로드된 시점이고, onDestroy는 창 닫힘 화면 이벤트라 여기서 IAP_ConfirmPurchase를 호출하면 안 돼요. 게임이 결제 완료를 확신할 수 있는 시점(결제 후 게임 복귀, 구매내역 확인 등)에 (2)의 OnConfirmPurchase로 확정해요.

=== "Native (Unreal)"

cpp
StovePCPurchaseOption option;
option.SetOperation(StovePCPurchaseOperation::WITH_WEBVIEW);
option.SetWebviewMode(Base::WebViewMode::INTERNAL);
option.SetWebviewRect(0, 0, 420, 700);
params.SetPurchaseOption(option);

IAP_StartPurchaseEx(&params,
    // onFinished: Point when payment window is displayed (not purchase completion). 0-won payment branching and transaction number storage are the same as (2)
    [](CallbackResult callbackResult, StovePCPurchaseResult purchaseResult) { /* Same as (2) */ },
    // onDestroy: Payment window closed. Only clean up UI and do not call ConfirmPurchase
    [](CallbackResult callbackResult)
    {
        Game::ShopUI::SetPurchaseButtonEnabled(true);
    });

=== "Unity"

csharp
var option = new StovePCPurchaseOption
{
    operation = StovePCPurchaseOperation.WITH_WEBVIEW,
    webviewMode = WebViewMode.INTERNAL,
    webviewPosX = 0, webviewPosY = 0, webviewWidth = 420, webviewHeight = 700,
};

IAP_StartPurchaseEx(param,
    // onFinished: Point when payment window is displayed (not purchase completion). 0-won payment branching and transaction number storage are the same as (2)
    (callbackResult, purchaseResult) => { /* Same as (2) */ },
    // onDestroy: Payment window closed. Only clean up UI and do not call ConfirmPurchase
    (callbackResult) =>
    {
        Game.ShopUI.SetPurchaseButtonEnabled(true);
    });

스팀 결제 (스팀런처 배포 게임)

StovePCPurchaseOption은 기본값 그대로 두고, 결제 완료 신호는 Steamworks의 MicroTxnAuthorizationResponse_t 콜백에서 받아 IAP_ConfirmPurchase로 확정해요. 이 콜백이 오지 않는 경우를 대비해 GameOverlayActivated_t로 오버레이 닫힘을 감지하는 경로도 담았어요. Steamworks 콜백 등록과 SteamAPI_RunCallbacks() 호출은 게임이 연동한 Steamworks SDK 영역이라 연결 지점만 표시했어요.

=== "Native (Unreal)"

cpp
#include "IAPSDK.h"
using namespace Stove::PCSDK;
using namespace Stove::PCSDK::Base;
using namespace Stove::PCSDK::IAP;

static int64_t  g_PendingTxnNo = 0;      // Order waiting for Steam payment result
static int64_t  g_LastTxnNo = 0;         // Transaction master number of this purchase (for late Steam callbacks/retries)
static int64_t  g_ConfirmingTxnNo = 0;   // Order currently undergoing IAP_ConfirmPurchase (prevents overlapping calls)
static uint64_t g_GraceDeadlineMs = 0;   // Grace period expiration time to wait for Steam callback after overlay closes (0 if none)

// (1) Start Purchase — Since the order of StartPurchase callback and overlay exposure is not guaranteed, store the transaction master number
void StartSteamPurchase()
{
    StovePCOrderProduct product; product.SetProductId(123); product.SetSalePrice(1000); product.SetQuantity(1);
    StovePCStartPurchaseParam params;
    params.CreateOrderProduct(1);
    params.SetOrderProduct(0, &product);   // StovePCPurchaseOption remains at default values

    Game::ShopUI::SetPurchaseButtonEnabled(false);
    IAP_StartPurchase(&params,
        [](CallbackResult callbackResult, StovePCPurchaseResult purchaseResult)
        {
            if (!callbackResult.GetResult().IsSuccessful())
            {
                Game::ShopUI::SetPurchaseButtonEnabled(true);
                if (callbackResult.GetExternalError() == 21107)
                {
                    // An incomplete previous Steam transaction remains — do not retry, inform the user, and clear the previous order status
                    Game::ShopUI::ShowMessage(L"A previous payment is in progress. Please complete or cancel it in the Steam overlay.");
                    ConfirmPendingPurchase(g_LastTxnNo);
                }
                return;
            }
            g_PendingTxnNo = g_LastTxnNo = purchaseResult.GetTransactionMasterNumber();   // Only this number is valid
        });
}

// (2) Steam payment result — Called from Steamworks MicroTxnAuthorizationResponse_t callback
void OnSteamMicroTxnAuthorized(bool authorized)
{
    int64_t txnNo = g_PendingTxnNo;
    g_PendingTxnNo = 0;
    g_GraceDeadlineMs = 0;
    if (txnNo == 0 && authorized) txnNo = g_LastTxnNo;   // Re-check if authorization arrives late after starting confirmation in the grace path

    if (!authorized || txnNo == 0)
    {
        Game::ShopUI::SetPurchaseButtonEnabled(true);   // Cancelled/Unauthorized — no payment. Unconfirmed orders are cleared by the backend
        return;
    }
    ConfirmPendingPurchase(txnNo);
}

// (3) When Steam callback is not received — Called from GameOverlayActivated_t callback. Restarts 3-second grace period whenever closed, stops when reopened
void OnSteamOverlayActivated(bool active)
{
    if (g_PendingTxnNo == 0) return;
    g_GraceDeadlineMs = active ? 0 : (Game::Clock::NowMs() + 3000);
    // If SteamServersDisconnected_t is received while waiting for payment, call ConfirmPendingPurchase(g_PendingTxnNo) immediately without grace period
}

void TickPurchaseWait()   // Called every frame in the game loop
{
    if (g_GraceDeadlineMs == 0 || Game::Clock::NowMs() < g_GraceDeadlineMs) return;
    g_GraceDeadlineMs = 0;
    int64_t txnNo = g_PendingTxnNo;
    g_PendingTxnNo = 0;
    ConfirmPendingPurchase(txnNo);   // If the grace period ends without a Steam callback, finalize the status with ConfirmPurchase
}

// (4) Confirm purchase — There is no automatic confirmation in the Steam flow. Call only after receiving the callback from the previous call
void ConfirmPendingPurchase(int64_t txnNo)
{
    if (txnNo == 0 || g_ConfirmingTxnNo != 0) return;
    g_ConfirmingTxnNo = txnNo;
    IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);
}
// status·purchasedProducts·chargeInfos are provided as default values, so determine only via CallbackResult
void OnConfirmPurchase(CallbackResult callbackResult, bool status,
                       StovePCPurchasedProduct* purchasedProducts, uint32_t purchasedProductsSize,
                       StovePCChargeInfo* chargeInfos, uint32_t chargeInfosSize)
{
    int64_t txnNo = g_ConfirmingTxnNo;
    g_ConfirmingTxnNo = 0;
    Game::ShopUI::SetPurchaseButtonEnabled(true);

    if (!callbackResult.GetResult().IsSuccessful())
    {
        if (callbackResult.GetExternalError() == 22001)
            return;   // Steam transaction unapproved (canceled/pending/expired) — process as cancellation
        if (callbackResult.GetResult().GetResultCode() == (uint32_t)Base::SDKResultCode::NETWORK_TRANSPORT_ERROR)
            Game::ShopUI::ShowNetworkRetry([txnNo]() { ConfirmPendingPurchase(txnNo); });   // Retry after network notification
        return;   // Other failures — do not grant items
    }

    // Confirmation complete — check payment results via inventory inquiry
    IAP_FetchInventory([](CallbackResult cb, StovePCInventoryItem* items, uint32_t itemsSize) { /* Refresh inventory UI */ });
}

=== "Unity"

csharp
using static Stove.PCSDK.Base;
using static Stove.PCSDK.IAP;
using Steamworks;   // Steamworks.NET integrated by the game

public class SteamPurchaseExample : MonoBehaviour
{
    long  _pendingTxnNo;      // Order awaiting Steam payment result
    long  _lastTxnNo;         // Transaction master number for this purchase (for late Steam callbacks/retries)
    long  _confirmingTxnNo;   // Order currently undergoing IAP_ConfirmPurchase (prevents overlapping calls)
    float _graceDeadline;     // Grace period expiration time to wait for Steam callback after overlay closes (0 if none)
    Callback<MicroTxnAuthorizationResponse_t> _microTxnCallback;
    Callback<GameOverlayActivated_t> _overlayCallback;

    void Start()
    {
        // Register Steamworks callbacks — SteamAPI.RunCallbacks() must also run in the game loop
        _microTxnCallback = Callback<MicroTxnAuthorizationResponse_t>.Create(OnSteamMicroTxnAuthorized);
        _overlayCallback = Callback<GameOverlayActivated_t>.Create(OnGameOverlayActivated);
    }

    // (1) Start purchase — Since the order of StartPurchase callback and overlay exposure is not guaranteed, store the transaction master number
    public void StartSteamPurchase()
    {
        var param = new StovePCStartPurchaseParam
        {
            products = new[] { new StovePCOrderProduct { productId = 123, salePrice = 1000, quantity = 1 } },
            productsSize = 1,   // option remains as default
        };

        Game.ShopUI.SetPurchaseButtonEnabled(false);
        IAP_StartPurchase(param, (callbackResult, purchaseResult) =>
        {
            if (!callbackResult.result.IsSuccessful())
            {
                Game.ShopUI.SetPurchaseButtonEnabled(true);
                if (callbackResult.externalError == 21107)
                {
                    // Previous incomplete Steam transaction exists — do not retry, notify user, and clear the previous order status
                    Game.ShopUI.ShowMessage("A previous payment is in progress. Please complete or cancel it in the Steam overlay.");
                    ConfirmPendingPurchase(_lastTxnNo);
                }
                return;
            }
            _pendingTxnNo = _lastTxnNo = purchaseResult.transactionMasterNumber;   // Only this number is valid
        });
    }

    // (2) Steam payment result — Steamworks callback
    void OnSteamMicroTxnAuthorized(MicroTxnAuthorizationResponse_t response)
    {
        long txnNo = _pendingTxnNo;
        _pendingTxnNo = 0;
        _graceDeadline = 0f;
        bool authorized = response.m_bAuthorized != 0;
        if (txnNo == 0 && authorized) txnNo = _lastTxnNo;   // If approval arrives late after starting confirmation from grace path, check again

        if (!authorized || txnNo == 0)
        {
            Game.ShopUI.SetPurchaseButtonEnabled(true);   // Canceled/Unapproved — no items granted. Backend will clear unconfirmed orders
            return;
        }
        ConfirmPendingPurchase(txnNo);
    }

    // (3) When Steam callback does not arrive — reset 3-second grace period every time it closes, stop when reopened
    void OnGameOverlayActivated(GameOverlayActivated_t response)
    {
        if (_pendingTxnNo == 0) return;
        _graceDeadline = response.m_bActive != 0 ? 0f : Time.time + 3f;
        // If SteamServersDisconnected_t was received while waiting for payment, call ConfirmPendingPurchase(_pendingTxnNo) immediately without grace period
    }

    void Update()
    {
        if (_graceDeadline == 0f || Time.time < _graceDeadline) return;
        _graceDeadline = 0f;
        long txnNo = _pendingTxnNo;
        _pendingTxnNo = 0;
        ConfirmPendingPurchase(txnNo);   // If the grace period ends and there is no Steam callback, finalize the status with ConfirmPurchase
    }

    // (4) Confirm Purchase — There is no automatic confirmation in the Steam flow. Call only after receiving the callback from the previous call
    void ConfirmPendingPurchase(long txnNo)
    {
        if (txnNo == 0 || _confirmingTxnNo != 0) return;
        _confirmingTxnNo = txnNo;
        IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);
    }

    // status·purchasedProducts·chargeInfos come with default values, so determine based on CallbackResult only
    void OnConfirmPurchase(CallbackResult callbackResult, bool status, StovePCPurchasedProduct[] purchasedProducts, StovePCChargeInfo[] chargeInfos)
    {
        long txnNo = _confirmingTxnNo;
        _confirmingTxnNo = 0;
        Game.ShopUI.SetPurchaseButtonEnabled(true);

        if (!callbackResult.result.IsSuccessful())
        {
            if (callbackResult.externalError == 22001)
                return;   // Steam transaction unapproved (canceled/pending/expired) — treat as canceled
            if (callbackResult.result.resultCode == (uint)BaseSDKResultCode.NETWORK_TRANSPORT_ERROR)
                Game.ShopUI.ShowNetworkRetry(() => ConfirmPendingPurchase(txnNo));   // Retry after network notification
            return;   // Other failures — do not grant items
        }

        // Confirmation complete — check grant results by querying the inventory
        IAP_FetchInventory((cb, inventoryItems) => { /* Refresh inventory UI */ });
    }
}

구매 검증

WITH_WEBVIEW나 DEFAULT 모드, 그리고 스팀 결제 동선에서는 결제 완료 후 IAP_ConfirmPurchase로 클라이언트 측 구매를 확정해요. 결과 판정은 위 스토브런처와 스팀런처를 한 가지 조건으로 판정하려면 의 JudgeConfirmPurchase를 쓰고, 게임 서버에서는 결제 유효성 체크 API로 2차 검증을 수행해야 해요.

=== "Native (Unreal)"

cpp
IAP_ConfirmPurchase(transactionMasterNumber,
    [](CallbackResult callbackResult, bool status,
       StovePCPurchasedProduct* purchasedProducts, uint32_t purchasedProductsSize,
       StovePCChargeInfo* chargeInfos, uint32_t chargeInfosSize)
    {
        if (JudgeConfirmPurchase(callbackResult, status) == ConfirmOutcome::Confirmed)
        {
            // Process item granting after secondary verification by the game server
        }
    });

=== "Unity"

csharp
IAP_ConfirmPurchase(transactionMasterNumber,
    (callbackResult, status, purchasedProducts, chargeInfos) =>
    {
        if (JudgeConfirmPurchase(callbackResult, status) == ConfirmOutcome.Confirmed)
        {
            // Process item granting after secondary verification by the game server
        }
    });

보관함 조회

IAP_FetchInventory로 로그인한 이용자의 구매 이력을 조회해요. 별도 매개변수 없이 호출하며, 결과 배열로 보관함 UI를 구성해요.

=== "Native (Unreal)"

cpp
IAP_FetchInventory(
    [](CallbackResult callbackResult, StovePCInventoryItem* inventoryItems, uint32_t inventoryItemSize)
    {
        if (callbackResult.GetResult().IsSuccessful())
        {
            // Configure inventory UI with inventoryItems[0..inventoryItemSize)
        }
    });

=== "Unity"

csharp
IAP_FetchInventory((callbackResult, inventoryItems) =>
{
    if (callbackResult.result.IsSuccessful())
    {
        // Configure inventory UI with inventoryItems
    }
});


**Game Withdrawal and Popup Cleanup**

The game withdrawal (withdrawal of terms of service) UI is displayed as `IAP_WithdrawGame`. When you need to immediately close all open IAP payment windows, call `IAP_CloseAllPopups`.
=== "Native (Unreal)"
```cpp
// 1) 게임 탈퇴(약관 철회) UI 표시
StovePCWithdrawGameOption withdrawOption;
withdrawOption.SetWebviewMode(Base::WebViewMode::INTERNAL);
withdrawOption.SetWebviewRect(0, 0, 800, 600);
IAP_WithdrawGame(&withdrawOption,
    [](CallbackResult callbackResult, bool gameWithdraw)
    {
        if (callbackResult.GetResult().IsSuccessful() && gameWithdraw)
        {
            // 게임해지(약관철회) 성공 시 로직을 구현해 주세요.
        }
    },
    [](CallbackResult callbackResult)
    {
        // 게임해지(약관철회) 팝업이 닫힌 후 로직을 구현해 주세요.
    });

// 2) 열린 결제 창 일괄 닫기
IAP_CloseAllPopups();

=== "Unity"

csharp
// 1) 게임 탈퇴(약관 철회) UI 표시
var withdrawOption = new StovePCWithdrawGameOption
{
    webviewMode = WebViewMode.INTERNAL,
    webviewPosX = 0, webviewPosY = 0, webviewWidth = 800, webviewHeight = 600,
};
IAP_WithdrawGame(withdrawOption,
    (callbackResult, gameWithdraw) =>
    {
        if (callbackResult.result.IsSuccessful() && gameWithdraw)
        {
            // 게임 탈퇴 성공 시 처리
        }
    },
    (callbackResult) =>
    {
        // 게임 탈퇴 팝업이 닫힌 후 처리
    });

// 2) 열린 결제 창 일괄 닫기
IAP_CloseAllPopups();

Server Integration

Prerequisites

  • To ensure proper billing operations, you must register all the following information in Partners.
Category Partners Menu Location Item Description
Billing Integration Info [Partners] > [Publishing Center] > [Manage Basic Billing Settings] > [Manage Billing Integration Info] Payment Completion Notification URL Game server URL to receive payment information after payment is completed
Refund History Notification URL Game server URL to receive refund information after receiving it from the market
Item Retrieval Notification URL Game server URL to process item retrieval when a refund request from the market is approved
  • Verify communication between the platform server and the game server
    • Communication verification between the platform server and the game server is required.
    • When receiving a payment completion notification, you must verify the payment validity by integrating with the Payment Validity Check API.

Development Flow

  1. Proceed with the payment request using the item list received through SDK integration.
  2. Once the payment request is made, payment information is delivered to the billing server via the SDK.
  3. The billing server verifies the validity of the payment information and then delivers the payment completion information to the game server registered in the Payment Completion Notification URL.
  4. The game server verifies the payment information via the validity API, provides the items, and then responds to the billing server.

Handling Abnormal Refunds


When a user requests a refund from the market, Stove Billing notifies the market of the consumption/retrieval status of the payment before the market confirms the refund, preventing refund abuse (refunding items that have already been consumed or sold). Stove Billing handles the market response for this step (Apple Send Consumption Information / Google orders.reviewrefund) internally, and the game server only needs to implement the Item Retrieval Request API, which is called when a refund request is delivered.


CategoryApple (App Store)Google (Google Play)
Refund Info Reception MethodApp Store Server Notifications V2 (SSN)Real-time Developer Notifications (RTDN, Cloud Pub/Sub)
Received Notification TypeCONSUMPTION_REQUESTpendingRefundReviewNotification
Stove Billing Response APISend Consumption Informationorders.reviewrefund
Stove Billing Response Timeout12 hours48 hours

!info
The response timeout is based on Stove Billing.
The 12-hour (Apple) and 48-hour (Google) limits are the deadlines for Stove Billing to report consumption information back to the market; the game server does not need to handle this separately. The game server only needs to respond normally to the Item Retrieval Request API below.


Item Retrieval Request API Response Specification


The game server must implement the API below. (This corresponds to the "Item Retrieval Notification URL" registered in Partners > Billing Settings.)

FieldValueDescription
item_statusintItem retrieval result: 0 Retrieval complete / 1 Retrieval failed
Step 2: Refund Repayment

This applies if the market proceeds with a refund despite a rejection response in Step 1 (Refund Review), or if a refund occurs in a market where Step 1 response is not possible (Steam). Such transactions are considered abnormal refunds, and the user must repay the amount upon their next login to continue normal gameplay.

Repayment Operation by Market

Market where refund occurredGoogle Release Version (Mobile)Apple Release Version (Mobile)Steam ClientStove PC Client
Refund from GoogleRepayment screen shownUsage restriction noticeUsage restriction noticeUsage restriction notice
Refund from AppleUsage restriction noticeRepayment screen shownUsage restriction noticeUsage restriction notice
Refund from SteamUsage restriction noticeUsage restriction noticeRepayment screen shownUsage restriction notice
No refund historyNormal entryNormal entryNormal entryNormal entry

!info
The timing for displaying the repayment screen or usage restriction notice may vary by game.
You can display it at a timing that suits your operational intent, such as after successful login, after entering the world, when selecting a character, when entering the shop, or when attempting a purchase.

Processing Flow — Checking Eligibility Upon Login

Processing Flow — Repayment Process (Mobile)

Processing Flow — Repayment Process (Steam)

Usage Restriction Notice Example

Game Usage Restriction Notice
Your game access has been temporarily restricted due to a refund for an item made through the market (Google, Apple, Steam, etc.). You can continue playing after accessing the game in the market where you requested the refund and repaying for the item.
Customer Support   Close

Repayment UI Configuration Guide

The basic repayment screen is provided to developers as a guide, and the actual design and content configuration are handled by each developer.

  • Guidance Text: Configured according to each game
  • Repayment Button: Shows the product payment screen by calling the SDK's startPurchase function
  • Customer Support Button: Navigates to inquiries by calling the SDK's customerSupport function
  • Refresh Button: Refreshes the list of items subject to repayment

Troubleshooting

Situation Cause Solution
Item delivery fails after payment is complete The billing server does not call the payment completion notification URL. You need to check the network between the game server and the billing server.
Market verification fails after payment is complete. This occurs if the configuration information for each market is entered incorrectly. After correcting the market verification information via Partners, you need to check again after up to 1 hour.

Sample Code

Payment Completion Notification Processing
text
--header 'caller-id: {{caller-id}}'

온라인 일반상품
{
    "bill_platform_type": "SHOP",
    "noti_type": "ONLINE_PURCHASE",
    "guid": "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"
}
온라인 장바구니상품
{
    "bill_platform_type": "SHOP",
    "noti_type": "ONLINE_CART_PURCHASE",
    "member_no": 11111
    "guid": "265265",
    "txn_time" : 1644807685000,
    "data": {
        "tid": "1909091033503333452",
        "products":[
        ]
        "product_id": "test_1",
        "product_price": 5000.0,
        "product_currency": "KRW",
        "inservice_item_id": "test_1",
        "service_order_id": "testtest_1234"
}
온라인 스팀 상품
{
    "bill_platform_type": "SHOP",
    "noti_type": "STEAM",
    "guid": "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",
    "guid": "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": ""
               }]
        }
}    



Payment Validity Check
  • Payment validity check
text
  {
    "code": 0,
    "message": "OK",
    "data": {
        "tid": "T202202103125",
        "products": [
            {
                "tid": 5128216388247371675,
                "product_id": "123456",
                "quantity": 1,
                "product_price": 5000.00,
                "product_currency": "KRW",
                "txn_time": 1644489139000,
                "inservice_item_id": "cp7892"
            },
            {
                "tid": 5128216388247323435,
                "product_id": "123457",
                "quantity": 1,
                "product_price": 55000.00,
                "product_currency": "KRW",
                "txn_time": 1644489139000,
                "inservice_item_id": "cp7893"
            }
        ]
      }
        }
  ...
Payment Validity Check (BULK)
  • Payment validity check (BULK)
text
curl --location --request POST 'https://api.onstove.com/bill-cpm/v1.0/payment/{service_id}/details' \
--header 'Authorization: Bearer {{access_token}}'
--header 'caller-id: {{caller-id}}'
{
    "details" : [
        {
            "tid": "T20220304125",
            "noti_type": "IAP_PURCHASE ",
            "bill_platform_type": "MOBILE",        
            "guid": "120552311123",
            "member_no": 123456
        },
        {
            "tid": "T20220304127",
            "noti_type": "ONLINE_PURCHASE",
            "bill_platform_type": "SHOP",
            "guid": "120552311150",
            "member_no": 123456
        }
    ]
}



Abnormal Refund
  • Receive abnormal refund list
text
{
    "data": {
        "total_count": 2,
        "list": [
            {
                "tid": 5675140483049940678,
                "market_code": "STEAM",
                "member_no": 100056315,
                "guid": "100056315",
                "character_no": 624462,
                "inservice_item_id": "Super_Gem13000",
                "market_item_id": "12345",
                "market_tid": "123456778",
                "market_user_id": "123455",
                "purchase_dt": 1699845522000,
                "voided_dt": 1623031862137
            },
            {
                "tid": 3675140483049940678,
                "market_code": "GOOGLE_PLAY",
                "member_no": 100056315,
                "guid": "100056315",
                "character_no": 624462,
                "inservice_item_id": "Super_Gem14000",
                "market_item_id": "a_market_product_id_01",
                "market_tid": null,
                "market_user_id": null,
                "purchase_dt": 1699845522000,
                "voided_dt": 1623031862137
            }
        ]
    },
    "code": 0,
    "message": "OK"
}



Item Retrieval Notification
  • Mobile (App Store / Google Play)
    • Request
NameTypeRequiredDefault ValueExampleDescription
tidLongY-1609997628158350014Order number provided when payment is completed in STOVE
guidStringY-200000006062Unique game user key
market_codeStringY-GOOGLE_PLAY, APPLE_APP_STOREMarket code requested for refund eligibility (GOOGLE_PLAY: Google, APPLE_APP_STORE: Apple)
product_idStringY-l_0001STOVE item ID
text
{
  "tid" : 1609997628158350014,
  "guid": "200000006062",
  "market_code": "GOOGLE_PLAY",
  "product_id": "l_0001"
}

NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0Response code
messageStringY-SuccessResponse message
dataJObjectY--Object containing retrieval decision results

data

NameTypeRequiredDefault ValueExampleDescription
decisionIntegerY-0Refund approval status (0: APPROVE, 1: REJECT)
item_statusIntegerY-00: Retrievable (item retrieval), 1: Not retrievable
text
{
  "code" : 0,
  "message":"성공",
  "data": {
    "decision":0,
    "item_status":0
  }
}

NameTypeRequiredDefault ValueExampleDescription
tidLongY-1609997628158350014Order number provided when payment is completed in STOVE
guidStringY-200000006062Unique game user key
market_codeStringY-ONLINEMarket code requested for refund eligibility (ONLINE: PC Online/Steam)
inservice_item_idStringY-l_0001Game company item ID
text
{
  "tid": 1609997628158350014,
  "guid": "200000006062",
  "market_code": "ONLINE",
  "inservice_item_id": "l_0001"
}

NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0Response code
messageStringY-SuccessResponse message
dataJObjectY--Object containing the result of the retrieval decision

data

NameTypeRequiredDefault ValueExampleDescription
decisionIntegerY-0Refund approval status (0: APPROVE, 1: REJECT)
item_statusIntegerY-00: Recoverable (retrieve item), 1: Not recoverable
text
{
  "code" : 0,
  "message":"성공",
  "data": {
    "decision":0,
    "item_status":0
  }
}

NameTypeRequiredDefault ValueExampleDescription
tidLongY-1609997628158350014Order number provided upon payment completion in STOVE
guidStringY-200000006062Unique key for the game user
market_codeStringY-ONLINE_CARTMarket code requested for refund eligibility (ONLINE_CART: Web store cart/bundle payment)
itemsArrayY--List of purchased items subject to retrieval (BULK processing)

items

NameTypeRequiredDefault ValueExampleDescription
tidLongY-1234567Order number for individual purchased item (Purchase detail TID)
inservice_item_idStringY-l_0001Game company item ID
text
{
  "tid": 1609997628158350014,
  "guid": "200000006062",
  "market_code": "ONLINE_CART",
  "items": [
    { "tid": 1234567, "inservice_item_id": "l_0001" },
    { "tid": 1234568, "inservice_item_id": "l_0002" }
  ]
}

NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0Response code
messageStringY-SuccessResponse message
dataJObjectY--Object containing the result of the retrieval decision

data

NameTypeRequiredDefault ValueExampleDescription
decisionIntegerY-0Refund approval status (0: APPROVE, 1: REJECT)
itemsArrayY--List of retrieval decision results per item (BULK processing)

items

NameTypeRequiredDefault ValueExampleDescription
tidLongY-1234567Order number for individual purchased item
item_statusIntegerY-00: Recoverable (retrieve item), 1: Not recoverable
text
{
  "code": 0,
  "message": "성공",
  "data": {
    "decision": 0,
    "items": [
      { "tid": 1234567, "item_status": 0 },
      { "tid": 1234568, "item_status": 0 }
    ]
  }
}

Frequently Asked Questions



Q1. What happens if I do not register billing information in Partners?
A. If IAP information for each market (market verification key, OAuth Client ID/Secret, Refresh Token, etc.) is not entered in Partners, the
item delivery request will not function properly after payment completion. Please ensure all items are registered before starting integration.
Q2. What should I do if I do not receive a payment completion notification or if processing fails?
A. For mobile billing, re-transmission is attempted up to 100 times at 1 to 5-minute intervals.
If it still fails after 100 attempts, you must manually process the delivery in [Partners] > [MobileBilling] > [View Sales History and Operations] > [Market Sales History].
Q3. How should I manage the TID?
A. The TID (STOVE Billing payment order number) must be stored and managed on the game server.
Since the same payment notification may be re-transmitted, logic to check for duplicate delivery based on the TID is essential.
Q4. How should the voided_tid field be handled when processing re-payment for abnormal refunds?
A. voided_tid If there is data in the field, it means the request corresponds to a re-payment after an abnormal refund.
In this case, the game server must be configured not to deliver the item, as this payment is used solely for re-payment purposes.
Q5. How should I manage items that have stopped selling when using the abnormal refund popup (STOVE common UI)?
A. The re-payment popup is structured so that re-payment occurs with the same refund item ID.
Even if an item has stopped selling in the mobile environment, it must remain in a 'for sale' state within STOVE Partners and the market.
You must not change it to a 'Disabled' state.
Q6. How do I receive subscription renewal notifications?
A. Pre-configuration for each market is required to receive subscription renewal notifications.
For iOS, you must change and register the server notification URL to version 2 notifications in App Store Connect, and
for Android, you must create a Google Cloud Pub/Sub Topic and Subscription, and register the STOVE Billing server URL as the endpoint.
Q7. How do I issue a Refresh Token for Google IAP integration?
A. You can issue it in the Google Developers OAuth 2.0 Playground.
In OAuth 2.0 Configuration, check "Use your own OAuth credentials", enter your OAuth Client ID and Client Secret, and
select the Play Android Developer API scope, then click Authorize API.
In Step 2, click the "Exchange authorization code for tokens" button to obtain the Refresh Token.
Enter the issued information in STOVE Partners > Billing Settings.
Q8. Are there any changes to the unapproved refund reception method for iOS after January 2025?
A. Yes, starting January 24, 2025, due to changes in the iOS receipt signing certificate, the app web address calling method has been discontinued and replaced by the App Store Server API calling method.
You must change the server notification URL from version 1 to version 2 in App Store Connect.
Q9. Are there any precautions regarding the WebView mode when integrating PC SDK billing?
A. The visibility of the purchase window varies depending on the WebView mode when the game screen is in Exclusive Fullscreen (FSE) mode.
WebViewMode::INTERNAL draws the window layered over the game screen, so the purchase window is not rendered in Exclusive Fullscreen mode.
WebViewMode::EXTERNAL draws as a separate window covering the entire screen, so the purchase window is displayed even in Exclusive Fullscreen mode, but there is an issue where the game screen is minimized as the separate window comes to the front.
Therefore, for games using Exclusive Fullscreen, it is recommended to switch the game screen to Borderless Windowed Fullscreen when opening the purchase window.



Do you have any inquiries?