Skip to content
스토브
마지막 업데이트

실제 적용 흐름이 궁금하신가요?

이용 시나리오 / 게임에서 구매하기

결제

이해하기


결제 지원 개요

스토브는 PC 온라인 결제와 모바일 마켓 결제, 두 가지 결제 종류를 지원해요.
결제 종류에 따라 지원 통화·결제 수단·한도·취소 방식이 달라요.

결제 종류 설명
PC 온라인 결제 PC 버전 게임의 웹상점·인게임 상점 결제 (스토브 제공 결제창 이용).
모바일 마켓 결제 구글·애플 등 앱 마켓 출시 게임의 결제 (마켓 제공 IAP(인앱 결제) 결제창 이용).

결제 계정 본인 확인
ㆍ 최소한의 본인 확인이 된 계정만 결제 가능
ㆍ 한국: 본인 인증 / 글로벌: 이메일 인증

스팀런처로 배포한 게임의 결제
스팀런처로 실행되는 게임의 결제도 PC 온라인 결제에 속하지만, 결제창이 스토브 결제 웹뷰가 아니라 스팀 결제 오버레이로 대체돼요. 자세한 동선은 개발하기 → PC IAP → 스팀 결제 를 참고하세요.

결제 지원 통화

분류 통화 설명 이 통화로 결제하는 계정
PC 온라인 결제KRW대한민국 원한국 가입 계정
USD미국 달러미국 가입 계정, 그리고 지원 통화가 없는 국가의 가입 계정
JPY일본 엔일본 가입 계정
EUR유로유로를 쓰는 지정 국가의 가입 계정 (하단 목록 참조)
THB태국 바트태국 가입 계정
PHP필리핀 페소필리핀 가입 계정
TWD대만 달러대만 가입 계정
모바일 마켓 결제-마켓 결제 지원 통화이용자의 각 마켓 계정에 설정된 지원 통화로 결제

※ 유로 결제 적용 국가 목록 (2026년 기준)37개
국가 명코드 국가 명코드 국가 명코드
독일 (Germany)DE에스토니아 (Estonia)EE올란드 제도AX
프랑스 (France)FR라트비아 (Latvia)LV생 바르텔레미BL
이탈리아 (Italy)IT리투아니아 (Lithuania)LT프랑스령 기아나GF
스페인 (Spain)ES룩셈부르크 (Luxembourg)LU과들루프GP
포르투갈 (Portugal)PT키프로스 (Cyprus)CY세인트 마틴MF
네덜란드 (Netherlands)NL몰타 (Malta)MT마르티니크MQ
벨기에 (Belgium)BE크로아티아 (Croatia)HR생피에르 미클롱PM
오스트리아 (Austria)AT안도라 (Andorra)AD레위니옹RE
핀란드 (Finland)FI모나코 (Monaco)MC남극 프랑스령TF
아일랜드 (Ireland)IE산마리노 (San Marino)SM마요트YT
그리스 (Greece)GR바티칸 시국 (Vatican City)VA불가리아*BG
슬로바키아 (Slovakia)SK코소보 (Kosovo)XK
슬로베니아 (Slovenia)SI몬테네그로 (Montenegro)ME

결제 통화 유의사항
ㆍ 불가리아: USD 결제·포인트 적립 제공
ㆍ 같은 상품의 결제 통화를 상점과 빌링 시스템에 동일하게 등록해야 결제돼요 (예: 상점 EUR·빌링 USD처럼 다르게 등록하면 결제 불가)

지원 결제 수단

분류 국가 설명
PC 온라인 결제 한국 스토브 페이(기본): 계좌이체·신용카드 간편결제, 1회 결제 한도가 크고 포인트 적립도 많음
그 외: 카카오페이·네이버페이·토스·페이코 등 간편결제, 휴대폰, 상품권류
글로벌 주요 결제수단: PayPal, Credit/Debit Card, ApplePay 등. 국가별 주력 결제수단 추가 제공 (예: 일본 PayPay)
모바일 마켓 결제 모든 국가 이용자가 마켓 계정에 등록한 결제 수단으로 결제 (수단 구성은 마켓이 결정하며 스토브·입점사가 관여할 수 없음)

결제사(PG) 이중화
ㆍ 주요 결제수단은 2개 이상 PG 연동 → 장애 시 자동 전환

미성년자 결제
ㆍ 상품권류만 기본 이용, 전체 수단은 보호자 동의 필요
ㆍ 보호자 동의: 본인인증으로 20세 이상 나이 차 확인 (보호자는 회원이 아니어도 무방, 유효 12개월)

결제 한도

게임에서 결제할 수 있는 금액에는 매월 게임별 한도가 있으며, 국가·플랫폼에 따라 기준이 달라요.

분류 국가 설명
PC 온라인 결제 한국 문화부 자율규제에 따라 PC 온라인 게임 한도 적용
ㆍ 성인: 10만원~3천만 원 자가 설정 (월 3회, 휴대폰 본인 인증 후 변경)
  ㆍ 설정한 한도는 명의자(주민번호) 기준으로 합산되며, 매월 게임별로 적용
ㆍ 미성년자: 월 7만원 한도, 변경 불가
글로벌 기본 한도 없음 (단, 결제수단 자체 한도는 있을 수 있음)
ㆍ 게임별 1회·1일·1개월 한도를 통화별 설정 가능
모바일 마켓 결제 모든 국가 결제 한도 없음 (단, 결제수단 자체 한도는 있을 수 있음)
PC 온라인 + 마켓 결제 일본 연령 구간별 구매 한도
일본에 서비스하는 게임에 적용 (전자금융거래법에 따른 사실상의 규제)
ㆍ 멀티플랫폼 게임은 PC·모바일마켓 구매 금액 합산
ㆍ 15세 이하: 월 5천엔
ㆍ 16세~17세: 월 3만엔
ㆍ 18세 이상: 제한 없음
ㆍ ※ 2022년 4월 일본 민법상 성인 연령 만 20세 → 만 18세 변경

일본 결제 한도 산정 방식
ㆍ 당월 1일~말일 누적 "엔화" 결제 금액 합산 (쿠폰·포인트 제외)
ㆍ 정회원 PC: 가입 국가가 일본인 경우 (일본 가입 = 엔화 결제)
ㆍ 정회원 모바일: 가입 국가가 일본이고 결제 통화가 엔화일 때만, 실제 엔화 결제액을 합산
ㆍ 게스트 PC: PC에는 게스트 회원이 없어 해당 없음
ㆍ 게스트 모바일: 가입 국가를 알 수 없어, 결제 통화가 엔화일 때만 실제 엔화 결제액을 합산
ㆍ 게임 내 모든 결제 금액을 합산 (재화성 상품뿐 아니라 전체 상품 포함)
ㆍ 구매하려는 상품 금액이 남은 한도를 넘으면 그 상품은 구매 불가 (남은 한도 안에서 살 수 있는 상품만 가능)

이용자별 특별 한도
ㆍ 특정 이용자(회원번호 기반)에 특별 한도 부여 가능 (마케팅·인플루언서 등)
ㆍ 게임 한도와 상충 시 이용자 특별 한도 우선 적용

결제 확인과 증빙

분류 설명
PC 온라인 결제 스토브 플랫폼에서 확인
ㆍ 결제/구매 완료 시 이메일 안내 (정보 없으면 미발송)
  ㆍ 실시간: 본인 결제 내역 (보호자는 자녀 결제 내역도 확인)
  ㆍ 월간: 전월 본인 결제 내역 (보호자는 자녀 결제 내역도 확인)
ㆍ '내정보'에서 결제 내역·적립 포인트 내역 확인
모바일 마켓 결제 각 마켓에서 확인
ㆍ 결제 통지 내역·인보이스·영수증으로 결제 정보 확인

현금 영수증 처리
ㆍ PC 온라인 결제: 결제사(PG) 처리, 국세청 홈페이지에서 확인 가능
ㆍ 모바일 마켓(구글 월렛): 스토브가 현금영수증 자동 발행

결제 취소

분류 설명
PC 온라인 결제 상점·아이템 결제 (한국 결제 수단)
청약 철회 기간 경과·상품 가치 훼손 여부로 환불 판단 (기간은 게임별 상이)
ㆍ 기간 이내 + 미사용: 원 결제 수단 승인 취소
ㆍ 기간 이내 + 사용: 부분 환불
ㆍ 기간 경과 + 미사용: 1000원과 10% 수수료 중 큰 금액 제하고 부분 환불
ㆍ 기간 경과 + 사용: 게임 정책에 따라 환불 제한 가능

상점·아이템 결제 (글로벌 결제 수단)
ㆍ 승인 취소 기간 내: 원 결제 수단 승인 취소
ㆍ 승인 취소 기간 경과: 취소 불가

스토어 게임
ㆍ 구매 후 14일 이내 + 누적 플레이 2시간 미경과 시 구매 취소 가능
ㆍ 취소 시 스토브 캐시 환급, 환급 캐시는 별도 현금 환불 신청 가능
모바일 마켓 결제 청약 철회 기간 경과·상품 가치 훼손 여부로 환불 판단

빌링 시스템과 연동

스토브 SDK를 통해 게임에 결제(IAP) 기능을 연동하는 방법을 안내해요.
Google Play, Apple App Store 등 주요 마켓의 인앱 결제와 PC 온라인 결제를 통합 지원하며, 구독 상품 및 비정상 환불 처리까지 포함한 결제 흐름 전반을 제공해요.

빌링 시스템 구성

스토브 빌링 시스템은 클라이언트 SDK와 서버 미들웨어로 구성돼요.

시스템명 설명
MultiPlatform-Middleware
(크로스플랫폼 미들웨어)
게임과 빌링(온라인/모바일) 통신을 담당하는 GATEWAY 서버.
IAP 모바일 빌링 서버.
Bill-WEB API 온라인 빌링 서버.
Game Server 게임 서버.

지원 기능

기능 설명
결제 완료 알림 결제(온라인/모바일) 완료 시 스토브 빌링이 게임 서버로 알림 전달.
미들웨어를 통해 유효성 확인 후 완료 응답 필요.
결제 유효성 확인 수신된 결제 알림의 출처를 스토브 빌링에서 검증.
BULK(리스트) 처리 지원.
게임 캐시 잔액 확인 게임에서 관리하는 유료 캐시 잔액 조회.
비정상 환불 처리 이용자가 마켓을 통해 직접 환불한 내역을 수집해 게임 서버로 전달.
Google, Apple 마켓 지원.
구독 상품 Google Play, Apple App Store의 자동 갱신형 구독 상품 지원.

사전 준비

정상적인 빌링 동작을 위해 파트너스에 아래 정보를 모두 등록해야 해요.
하나라도 누락되면 결제가 정상적으로 이루어지지 않아요.

구분 등록 내용
빌링 연동 정보 빌링 버전(V4)·서비스 타입·GUID 사용여부·결제 완료 알림 URL·캐시 조회 URL
마켓별 IAP 정보 Google·Apple 마켓 인증 정보
마켓 상품 정보 마켓별 상품 ID
월드 정보 Noti URL용 기본 월드(world_id)

마켓 연동 정보 주의
ㆍ Apple IAP Key: 최초 다운로드 후 재다운로드 불가 (분실 시 재발급)
ㆍ Apple 공유 암호 재생성 시 사용 중인 모든 앱 정보 업데이트 필요

비정상 환불 처리

이용자가 아이템을 받은 뒤 운영자를 거치지 않고 마켓에서 직접 환불(취소)하면, 받은 아이템을 계속 쓰지 못하도록 막는 기능이에요.
스토브 빌링은 이를 위해 환불 확정 전 개입해 어뷰징을 막는 단계와 환불이 확정된 뒤 손실을 복구하는 단계, 2단계로 대응해요.

단계 목적 적용 마켓
1단계
환불 검토
마켓이 환불을 확정하기 전에 개입해, 이미 소비·판매한 상품의 환불(환불 어뷰징)을 방지 Google Play, Apple App Store
(Steam은 사전 피드백 절차가 없어 미지원)
2단계
환불 재결제
1단계에서 거부 의견을 냈음에도 마켓이 환불을 강행 처리한 경우, 이용자가 다음 접속 시 재결제하도록 하여 손실을 복구 Google Play, Apple App Store, Steam

1단계에서 막지 못한 건이 2단계로 이어져요
마켓이 개발자(스토브) 의견을 반영하지 않고 환불을 강행 처리하면, 해당 건은 2단계(환불 재결제) 대상으로 넘어가요. 두 기능은 별개로 동작하지만 순차적으로 연결돼요.

비정상 환불 수집 대상
ㆍ 1단계(환불 검토): Google Play·Apple App Store 일반 상품 환불 요청 건
ㆍ 2단계(환불 재결제): Google Play·Apple App Store·Steam 환불 확정 건
ㆍ 모바일 구독 상품: 비정상 환불 판정 불가로 제외
ㆍ 게임 탈퇴 사용자도 환불 발생 시 정보 전달

개발하기


파트너스 및 콘솔 설정

  • Google Console API 설정
      1. Google Play Console API 액세스 권한 얻기
      1. Google Cloud 프로젝트 생성 (프로젝트 만들기 / API 추가 / OAuth 동의 화면 설정 및 클라이언트 ID 생성)
      1. OAuth 2.0 Playground Refresh Token 생성
      1. 스토브 파트너스 빌링 설정 정보 입력

  • 빌링 정보 입력 가이드
    • 구글 플레이 빌링 정보 등록 (마켓 검증 키 / OAuth Client ID / OAuth Client Secret / Refresh Token / Bucket Name / Credential json)
    • 애플 앱 스토어 빌링 정보 등록 (Issuer ID / Key ID / IAP Key / 공유 암호)

  • 비 승인 환불 상품 내역 수신 설정
    • iOS App Store 알림 설정 (QA·프로덕션 서버 URL / 버전 2 알림 변경)
    • Android 알림 설정

SDK 연동

모바일 IAP

Android는 PlayBilling, iOS는 StoreKit을 사용해 결제 흐름을 처리해요. SDK가 마켓 호출과 스토브 빌링 서버 검증까지 연결해 주지만, 게임 서버 측 결제 알림(Noti) 수신·재검증·지급 처리는 별도로 구현해야 해요.

사전 준비
  • 모듈 의존성
    • Android (build.gradle): 아래 저장소·의존성을 추가하세요. (릴리즈 최신 버전을 확인해서 적용하세요.)
      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): Build Settings → Capabilities에서 In-App Purchase를 검색해 추가하고 활성 상태인지 확인하세요.
  • 파트너스 빌링 정보 등록: Google Play / Apple App Store 빌링 키·시크릿이 파트너스에 등록돼 있어야 해요. (2. 연동 가이드 > Google Play 연동 / Apple App Store 연동 참고)
  • 결제 알림(Notification) URL 등록: 게임 서버 측 결제 알림 수신용 URL을 파트너스에 등록하세요. SDK 결제 완료 후 이 URL로 지급 요청이 전달돼요. (모바일은 최대 100회 재시도)
  • 이용자 로그인 완료: 모든 IAP 호출은 Auth.login 완료 이후에만 동작해요. 미로그인 상태에서 호출하면 Auth.UnauthorizedError(30002)가 반환돼요.
  • 멀티캐릭터(다중 재화) 사용 시: 파트너스 SDK Config에서 use_custom_billing_guid (true)를 설정하세요. 클라이언트는 IAP 초기화 직후 + 월드/캐릭터 선택 완료 시점에 setCustomBillingGUID를 반드시 호출해야 해요. (코드는 아래 샘플 코드의 필수 멀티캐릭터(다중 재화) 관리 설정 단락 참고)
개발 흐름
  1. 초기화: 로그인 완료 이후 IAP.initialize를 호출하세요. 실패 시 Auth.UnauthorizedError(30002)는 로그인 흐름으로 유도하고, IAPError.InitializeError(40003)면 userInfo의 responseCode(BillingClient.BillingResponseCode)와 debugMessage로 마켓 환경 점검을 안내하세요.
  2. 결제 리스너 등록: 초기화 성공 콜백 안에서 IAP.setListener로 결제 결과 콜백을 등록하세요. 정상 구매·취소·계정 불일치·검증 대기·지급 대기·마켓 오류가 모두 이 리스너로 전달돼요.
  3. 상점 구성: IAP.fetchProducts로 상품 목록을 조회하고, 응답 IAPProduct의 ProductState(Available / Waiting / Purchased) 값에 따라 구매 버튼 활성/비활성을 분기 처리하세요.
  4. 구매 진행: Available 상품에 한해 IAP.startPurchase를 호출하세요. Waiting은 진행 중이므로 버튼 비활성화, Purchased는 미지급 상태이므로 IAP.flush로 재지급 처리하세요.
  5. flush: 결제됐지만 미지급 상품이 있을 때 또는 앱 재실행 시 IAP.flush를 호출해 컨슘·재지급 요청을 진행하세요. 결과는 setListener 콜백으로 돌아와요.
  6. (옵션) 부가 기능: developer payload 전달은 serviceOrderId 인자로, 환불 내역 조회는 IAP.handleVoidedPurchases, iOS App Store 프로모션 상품 결제는 purchasePromotion을 사용하세요.

결제 검증은 게임 서버에서 수행하세요
SDK 콜백의 isSuccessful만으로 아이템을 지급하지 마세요. 클라이언트는 위변조 가능하므로 게임 서버가 결제 알림(Noti) 수신 후 스토브 결제 유효성 체크 API로 2차 검증한 뒤 재화/아이템을 지급하세요.

트러블슈팅

결제 검증 대기·지급 대기는 정상 흐름의 일부예요
IAPError.PurchasedError(40006)와 IAPError.WaitingError(40001)는 결제·지급이 빌링 서버에서 비동기로 처리되는 정상 상태예요. 이용자에게 오류로 안내하지 말고 "결제가 처리 중이에요, 잠시 후 푸시로 알려드려요" 같은 진행 안내 화면으로 띄우세요. 일정 시간 후 빌링 서버에서 자동 처리되며 결과는 푸시로 전달돼요.

계정 불일치(SuccessButUserMissMatch, 40000) 처리
결제 검증이 끝나기 전 이용자가 계정을 변경하거나 월드를 이동했을 때 발생해요. 현재 로그인된 계정 기준으로 재로그인 흐름을 유도하고, 이전 결제 결과는 게임 서버 측 알림(Noti)으로 추후 처리됨을 안내하세요.

상황원인조치
Auth.UnauthorizedError (30002)로그인 미완료 또는 토큰 만료AuthUI.login 또는 Auth.login으로 재로그인 흐름을 진행한 뒤 IAP 호출을 다시 시도하세요.
IAPError.InitializeError (40003)Android 마켓(PlayBilling) 초기화 실패userInfo의 responseCode(BillingClient.BillingResponseCode)와 debugMessage를 확인해 스토어 앱 설치·로그인 상태·지원 마켓 여부를 점검하도록 이용자에게 안내하세요.
IAPError.InvalidProduct (40004)임의로 만든 product 객체 또는 fetchProducts 결과 외 상품으로 결제 시도반드시 IAP.fetchProducts로 받은 객체를 그대로 startPurchase에 전달하세요. 직접 인스턴스화한 product는 사용하지 마세요.
IAPError.MarketError (40002)결제 시도 중 마켓 클라이언트 오류Android는 userInfo.responseCode(BillingResponseCode), iOS는 SKError.code로 분기해 이용자에게 안내하세요. 일시 오류면 재시도, 환경 문제면 마켓 앱·계정 점검 안내.
iOS pay country code nil (40010)Apple 계정의 결제 국가 정보 누락App Store 설정에서 국가/지역과 결제 정보를 등록하도록 안내하세요.
서버 빌링 검증 실패 (30000 verify fail / 30015 sandbox transaction)결제 영수증 검증 실패 또는 LIVE 환경에서 테스트 계정 미등록LIVE 환경이면 파트너스에 테스트 계정 등록 여부를 확인하세요. 일반 케이스는 게임 서버의 영수증 재검증 로직을 점검하세요.
이미 구독 중인 상품 (93106)동일 구독 상품을 이용자가 이미 보유이용자에게 이미 구독 중임을 안내하고 구매 버튼을 비활성화하세요.
결제 후 지급 누락게임 서버 알림(Noti) URL 응답 실패 또는 처리 누락파트너스에 등록된 알림 URL이 항상 200 응답을 주는지 확인하세요. 모바일은 최대 100회 재지급을 시도하므로 게임 서버 측 멱등(idempotent) 처리도 함께 구현하세요.
멀티캐릭터에서 잘못된 캐릭터로 지급setCustomBillingGUID 미호출 또는 잘못된 시점에 호출IAP 초기화 후 + 월드/캐릭터 선택 완료 시점에 setCustomBillingGUID("{STOVE_guid}_{STOVE_character_no}")를 호출하세요.
환불 내역 조회 UI에서 40303 반환인증 토큰 만료OperationUI.HandleResult에 위임 후 Auth.logout으로 강제 로그아웃을 수행해 재로그인을 유도하세요.

각 함수별 세부 ErrorCode 표는 아래 샘플 코드 안에 함께 포함돼 있어요.

샘플 코드

초기화

Market SDK(PlayBilling/StoreKit)를 초기화해요. 초기화가 완료돼야 상품 조회·구매 호출이 가능해요.

  • 추천 시점: 로그인 성공 이후

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. Android PlayBilling의 경우 userInfo의 'responseCode'와 'debugMessage' 참조
com.stove.iap40010iOS에 한해서만 pay country code가 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

IAP 초기화 성공 이후 결제 결과를 받을 리스너를 설정해요. flush의 처리 결과도 이 리스너로 전달돼요.

  • 추천 시점: 초기화 완료 직후
  • product 값이 있으면 구매 시도한 상품 상태를 응답받은 상태로 변경해요. 특정 상황에서 Available 이외의 상태가 올 수 있어요.

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: 결제 실패)
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 (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



상점 구성하기

마켓에서 상품을 조회해 상점을 구성해요. 조회 응답인 IAPProduct의 주요 필드는 다음과 같아요.


IAPProduct 필드

필드명설명예시
ProductType상품 종류 (inapp/subs)inapp
productIdentifier마켓 등록 상품ID (구매 요청 시 전달)google_item01
stoveProductId스토브 파트너스에 등록된 상품IDstove_item01
localizedTitle마켓 상품명전투 방패
localizedDescription마켓 상품 설명상품 설명...
price가격 (노출용 금액)₩1,100
priceCurrencyCode통화 코드KRW, JPY, USD
priceAmountMicros가격을 마이크로 단위 (÷1,000,000 = 실제 금액)1100000000
ProductState상품 상태Available / Waiting / Purchased
isLimit구매 제한 여부false
purchaseLimit구매 제한 정보 (3.1.0 이상, 아래 표 참고)-
subscriptionPeriod구독 기간 (ISO 8601)P1M
freeTrialPeriods무료 체험 기간 (ISO 8601)P7D

구매 제한 정보 (3.1.0 이상)

3.1.0 부터 상품마다 계정 · 캐릭터 · 월드 기준의 구매 제한 수량과 지금까지 구매한 수량이 함께 내려와요. 상점에서 1/5 처럼 구매 가능 수량을 표시할 때 사용해요.

필드명설명예시
accountPurchasedCount계정 기준 구매 수량1
accountLimit계정 기준 구매 제한 수량 (0 = 제한 없음)5
characterPurchasedCount캐릭터 기준 구매 수량0
characterLimit캐릭터 기준 구매 제한 수량 (0 = 제한 없음)0
worldPurchasedCount월드 전체 구매 수량 (모든 이용자 합계)120
worldLimit월드 기준 구매 제한 수량 (0 = 제한 없음)1000
  • 필드 이름은 플랫폼 표기를 따라요. Android · iOS · Unreal 은 purchaseLimit.accountLimit, Unity 는 PurchaseLimit.AccountLimit 이에요.
  • 제한 수량이 0 이면 그 기준으로는 제한이 없는 상품이에요. 구매 제한 정보를 받지 못했을 때도 모든 값이 0 으로 내려오고, 상품 목록 조회는 그대로 성공해요.
  • 구매 수량은 캐릭터 설정(setGameProfile) 으로 캐릭터와 월드를 설정한 뒤 조회해야 채워져요. 설정 전에 조회하면 제한 수량은 내려오지만 구매 수량은 0 이에요.
  • 수량은 조회 시점 기준이에요. 실제 구매 가능 여부는 결제할 때 서버에서 다시 확인해요.
  • 기존 isLimit 도 그대로 제공돼요.

📌 구매 제한 정보는 스토브 측 설정이 활성화된 게임에만 내려가요. 사용하려면 담당 기술 PL 에 문의해 주세요.

📌 3.1.0 구매 제한 정보는 iOS · Android · Unity · Unreal 에서 제공하며, Android 는 Google Play 한정이에요. 화웨이 · 원스토어에서는 지원하지 않는 기능이에요.

권장 사항: 상품 상태별로 구매 버튼을 다르게 표시해요.

  • Available: 구매 가능 상태
  • Waiting: 결제 진행 대기 상태 (구매 시도 중)
  • Purchased: 구매 완료했으나 지급이 안 된 상태 (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 { /* 네트워크 오류 */ }
    });
}

구매 제한 표시하기 (3.1.0 이상)

상점에는 아래 순서로 구매 제한을 표시해요.

  1. 제한 수량이 0 인 기준은 표시하지 않아요.
  2. 기준마다 남은 수량(제한 수량 - 구매 수량)을 계산해요.
  3. 한 기준이라도 남은 수량이 없으면 구매 버튼을 비활성화해요.
  4. 결제가 끝나면 상품 목록을 다시 조회해 수치를 갱신해요.
기준의미표시 예시
계정이 계정으로 구매할 수 있는 수량계정당 1/5
캐릭터지금 캐릭터로 구매할 수 있는 수량캐릭터당 0/1
월드월드의 모든 이용자가 함께 쓰는 한정 수량남은 수량 880
  • 월드 구매 수량은 모든 이용자의 합계예요. 내 구매 횟수가 아니라 남은 수량으로 보여 주는 것을 권장해요.
상태조건버튼 예시
제한 없음제한 수량이 모두 0구매
구매 가능모든 기준에 남은 수량이 있음구매 + 제한 문구
구매 한도 도달계정 또는 캐릭터 기준 남은 수량 없음구매 완료 (비활성)
품절월드 기준 남은 수량 없음품절 (비활성)
  • 구매 제한보다 상품 상태(ProductState)를 먼저 확인해요. Waiting · Purchased 상품은 위 권장 사항대로 처리해요.
  • 상점에 들어올 때 · 캐릭터를 바꿨을 때 · 결제가 끝났을 때 상품 목록을 조회해요. 수치는 조회 시점 기준이에요.
  • 화면 표시는 안내용이에요. 조회 이후 다른 기기나 다른 이용자의 구매로 한도가 찰 수 있고, 이때는 결제 단계에서 서버가 구매를 거절해요. 결제 실패를 받으면 상품 목록을 다시 조회해 화면을 갱신해요.
  • 구매 제한 정보를 받지 못해 값이 모두 0 이면 제한 문구 없이 구매 버튼만 표시돼요.

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



구매하기

상품의 ProductState에 따라 다르게 처리해요. Available인 경우만 startPurchase를 호출하고, Purchased는 flush로 재지급 처리해요.


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

결제는 됐지만 아직 지급 전인 상품의 컨슘 처리 및 상품 재지급 요청 용도예요. 처리 결과는 IAP.setListener에 설정된 리스너로 전달돼요.


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

결제 시 developer payload 설정

결제 호출 시 serviceOrderId를 설정하면 결제 응답에서 확인할 수 있어요.

⚠️ 주의
payload 값은 이용자의 일부 재지급 케이스(앱 삭제 등)에서 100% 전달이 보장되지 않아요.
지급에 영향을 주는 주요 정보로는 사용하지 않도록 주의하세요.


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

환불 내역 조회 (데이터)

이용자의 마켓 환불 내역을 화면 없이 데이터로만 받아요. 환불 내역이 있는 이용자에게 게임에서 직접 재결제를 안내하거나 접속을 제한할 때 써요. SDK 가 제공하는 화면으로 처리하려면 아래 환불 내역 조회 UI(handleVoidedPurchases)를 쓰세요.


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



환불 내역 조회 UI

이용자의 마켓 환불 내역을 화면에 노출해요. 환불 결제가 필요한 경우 이 화면에서 처리할 수 있어요.


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();
                }
            });
        }
    });
}

필수 멀티캐릭터(다중 재화) 관리 설정

필수 적용 대상
다음 중 하나라도 해당하면 멀티캐릭터 사용 설정이 필수예요.

  • 다중 월드로 서비스되는 게임 (월드별 캐릭터·아이템 지급)
  • 단일 서버지만 내부 캐릭터가 있고 캐릭터별 결제·지급이 필요한 경우
  • 파트너스 월드 설정이 2개 이상인 경우
  • 스토브 2차 재화 시스템과 결제(IAP) 기능을 함께 사용하는 경우

파트너스(SDK Config) 설정

파트너스 SDK Config에서 아래 항목을 설정해야 해요.

  • use_custom_billing_guid = true

클라이언트 작업 - 이용자 유니크 식별자 설정

  • 설정 시점: SDK IAP 객체 생성(초기화) 직후, 상품 지급받을 이용자 설정(setCustomBillingGUID)을 반드시 해야 해요. 단, 월드 또는 캐릭터가 선택된 이후에 설정하도록 주의하세요.
  • 설정 방식 (스토브 게임 캐릭터 기능 사용 시, 표준 권장 방식): {STOVE_guid}_{STOVE_character_no} 조합 형태로 설정해요. 이 방식으로 설정하더라도 결제 완료 후 빌링 서버 지급 요청 시 character_no 필드는 정상적으로 전달돼요.

안내사항 (2025.05.15)
신규 게임의 경우 '계정 선물하기' 등 다양한 기능에 유연하게 대응하기 위해, {STOVE_guid}_{STOVE_character_no} 조합 형태로 가이드가 변경됐어요. 본 설정은 모바일 환경에서만 적용돼요.


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

iOS Promoted

App Store 내 프로모션 상품 결제 연동이에요.

  • iOS 11 이상부터 사용 가능
  • purchasePromotion 호출 시점은 초기화·로그인 완료 이후

코드 예시 (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

사전 준비
  • BaseSDK 초기화(Base_Initialize)와 이용자 로그인 완료가 선행돼야 해요. 이어서 IAP_Initialize(shopKey)로 IAPSDK를 초기화해요. 부모 창 지정이 필요하면 IAP_InitializeWithWndInfo를 사용해요.
  • 게임 루프에서 콜백 러너(Base_RunCallback())가 주기적으로 호출돼야 비동기 콜백이 동작해요.
  • 파트너스에 결제 알림(Notification) 수신 URL과 마켓별 빌링 정보(Google/Apple/Steam)가 등록돼 있어야 해요.
  • 멀티캐릭터(다중 재화) 사용 시 게임 프로필 설정 API로 이용자 식별자를 먼저 설정해요.
  • 스팀런처로 배포하는 게임은 외부플랫폼연동모듈(APIModule)로 스토브 인증을 마치고 PCSDK3가 기동된 상태여야 하며, 게임이 Steamworks SDK를 직접 연동·초기화해야 해요. 자세한 동선은 아래 스팀 결제 를 참고하세요.

개발 흐름
  1. 초기화: Base_Initialize 완료 후 IAP_Initialize(shopKey)(부모 창이 필요하면 IAP_InitializeWithWndInfo)로 IAP 모듈을 초기화해요.
  2. 약관 동의 확인: IAP_FetchTermsAgreement로 필수 약관 동의 여부를 조회하고, 미동의 시 약관 동의 흐름을 진행해요.
  3. 상점 구성: 카테고리 조회(IAP_FetchShopCategories)와 상품 목록 조회(IAP_FetchProducts)로 상품 목록을 가져와 UI를 구성해요.
  4. 구매 진행: 이용자 선택 시 IAP_StartPurchase/IAP_StartPurchaseEx를 호출해요. StovePCPurchaseOption의 operation으로 결제 UI와 확정 방식을, webViewMode로 결제창 표시 방식을 정해요. (아래 구매 옵션과 결제창 표시 방식 참고) 조회한 상품 정보를 구매 파라미터에 옮겨 담는 방법은 아래 상품 조회 결과를 구매 파라미터로 옮기기 를 참고하세요.
  5. 구매 확정/검증: 결제 완료 후 IAP_ConfirmPurchase로 클라이언트 측 확정을 호출하고, 게임 서버에서는 결제 유효성 체크 API로 2차 검증을 수행해요.
  6. 보관함: 필요 시 인벤토리 조회(IAP_FetchInventory)를 활용해요.
  7. 부가 동작: 게임해지(약관철회) UI는 IAP_WithdrawGame, 열린 결제 창 일괄 닫기는 IAP_CloseAllPopups를 사용해요.
  8. 정리: 게임 종료 직전에 IAP_UnInitialize()로 IAP 모듈을 정리한 뒤 Base_UnInitialize()를 호출해요.

스팀런처 배포 게임은 4~7단계가 달라요. 아래 스팀 결제 를 참고하세요.


구매 옵션과 결제창 표시 방식

IAP_StartPurchase/IAP_StartPurchaseEx를 호출할 때 StovePCPurchaseOption으로 두 가지를 정해요. operation(SetOperation)은 결제창을 SDK가 띄울지와 구매 확정을 SDK가 대신할지를 정하고, webViewMode(SetWebviewMode)는 SDK가 띄우는 결제창을 게임 창 안에 겹쳐 그릴지 별도 창으로 그릴지를 정해요. 약관 동의 조회(IAP_FetchTermsAgreement)의 StovePCTermsOption과 게임해지(IAP_WithdrawGame)의 StovePCWithdrawGameOption에도 같은 webViewMode 항목이 있어 아래 설명이 그대로 적용돼요.

구매 옵션 (operation)

값결제창 표시구매 확정(ConfirmPurchase)완료 결과 전달 위치
StovePCPurchaseOperation::WITH_WEBVIEW_AND_CONFIRM_RESULT (권장)SDK 웹뷰SDK가 자동 호출IAP_StartPurchase(Ex)의 onFinished 콜백
StovePCPurchaseOperation::WITH_WEBVIEWSDK 웹뷰게임이 직접 호출IAP_ConfirmPurchase 콜백
StovePCPurchaseOperation::DEFAULT표시하지 않음. 결과로 받은 1회용 결제 URL(oneTimePaymentUrl)을 게임이 직접 열어요게임이 직접 호출IAP_ConfirmPurchase 콜백

ㆍ WITH_WEBVIEW_AND_CONFIRM_RESULT: 결제 완료 감지와 구매 확정까지 SDK가 처리하니 IAP_ConfirmPurchase를 따로 호출하지 마세요(호출하면 중복 확정). 0원 아이템도 SDK가 내부에서 처리해 같은 onFinished 콜백으로 전달해요.
ㆍ WITH_WEBVIEW: SDK가 결제창은 띄우지만 결제 완료를 알려 주지 않아요. onFinished는 결제창에 URL이 로드된 시점에 오고, onDestroy는 화면 정리 이벤트일 뿐 결제 완료 신호가 아니에요. 게임이 IAP_ConfirmPurchase를 직접 호출해야 하므로 특별한 이유가 없으면 권하지 않아요.
ㆍ DEFAULT: SDK는 주문을 만들고 1회용 결제 URL을 돌려주는 데서 끝나요. 결제창을 여는 일과 IAP_ConfirmPurchase 호출은 모두 게임이 해요. SDK가 결제창을 띄우지 않으므로 SetWebviewMode와 SetWebviewRect는 적용되지 않고, onDestroy도 호출되지 않아요.

DEFAULT 옵션 사용 순서

자체 내장 브라우저(CEF, Unity 웹뷰 등)에 결제 페이지를 넣거나 게임 UI 흐름에 맞춰 결제 창을 직접 제어해야 할 때 DEFAULT를 선택해요. SDK가 결제창을 띄우고 결과까지 알려 주는 것으로 충분하다면 WITH_WEBVIEW_AND_CONFIRM_RESULT가 더 간단해요.

  1. 주문 생성: IAP_StartPurchase(Ex)를 호출하면 onFinished로 거래 번호(transactionMasterNumber)와 1회용 결제 URL(oneTimePaymentUrl)이 와요. 이 시점은 결제 전이에요. 거래 번호는 비정상 종료에 대비해 로컬에 저장하고, 재시작 시 저장된 번호가 있으면 IAP_ConfirmPurchase로 마무리하세요.
  2. 0원 결제 확인: purchaseProgress가 NOT_NEED_PAYMENT_WINDOW이면 결제 URL이 없고 이미 구매가 끝난 상태예요. 창을 열지 말고 바로 IAP_ConfirmPurchase를 호출해 지급 목록을 받으세요.
  3. 결제창 표시: 받은 URL을 원하는 브라우저 컴포넌트로 열어요. SDK가 결제 페이지와 따로 통신하지 않으므로 브라우저에 연동 코드를 넣을 필요가 없어요. 결제 페이지는 결제 수단에 따라 새 창을 열 수 있으니 새 창 열기를 허용해 두세요. URL은 1회용이라 다시 시도하려면 IAP_StartPurchase를 다시 호출해요.
  4. 구매 확인: 결제창이 닫히면 보관해 둔 거래 번호로 IAP_ConfirmPurchase를 무조건 한 번 호출하세요. 조회 API라 결제를 안 했든 취소했든 호출해도 부작용이 없어요. 첫 조회가 미확정이면 5초 뒤 한 번만 다시 조회하고, 그래도 미확정이면 "결제 확인" 버튼으로 사용자가 다시 확인하게 하세요. 사용자가 창을 닫지 않고 게임으로 돌아올 수 있으니 이 버튼은 결제 중에 항상 노출하세요. 앞선 콜백이 오기 전에 같은 API를 다시 호출하면 콜백이 덮어써지므로 겹쳐 호출하지 마세요.
  5. 아이템 지급: 아래 세 갈래 판정에서 결제 완료로 확인된 경우에만 지급해요.

ConfirmPurchase 결과는 세 갈래로 읽어요

콜백 결과뜻게임이 할 일
IsSuccessful() == true 이고 status == true결제 완료purchasedProducts를 기준으로 아이템을 지급해요.
IsSuccessful() == true 이고 status == false결제 미완료(취소, 아직 결제 안 함, 서버 반영 전)지급하지 않아요. 결제창을 닫은 직후라면 5초 뒤 한 번만 다시 조회해요.
IsSuccessful() == false조회 실패(네트워크, 서버 오류, 잘못된 거래 번호)지급하지 않아요. 재시도하거나 사용자에게 안내해요. 미승인 주문은 external_error 22001로 올 수 있으며, 이 경우도 미완료로 다뤄요.

스토브런처와 스팀런처를 한 가지 조건으로 판정하려면

위 표는 스토브런처 동선 기준이에요. 스팀런처 동선에서는 SDK가 status를 항상 false로 내려주므로, IsSuccessful과 status를 함께 보는 조건을 그대로 쓰면 스팀에서 확정된 결제가 실패로 처리돼요. 콜백 값만으로는 두 동선을 구분할 수 없고 조회 API도 없으니, 외부플랫폼연동모듈로 스토브 인증을 마친 시점에 플래그를 세워 두고 아래처럼 한 함수에서 판정하세요. SDK는 그 초기화 때 넘긴 스팀 유저 아이디(SteamUserId)가 있으면 스팀 결제 동선으로, 없으면 스토브 결제창 동선으로 자동 처리해요.

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회 재조회
}

자주 하는 실수

  • onFinished를 받은 시점에 아이템을 지급하거나 ConfirmPurchase를 바로 호출하는 것. 이 시점은 결제 전이에요.
  • 결제창이 닫혔다는 사실만으로 결제 완료로 판단하는 것. 닫힘은 결제 여부와 무관하며, ConfirmPurchase 결과로만 판단해요.
  • status == false를 오류로 처리해 사용자에게 실패 안내를 띄우는 것. 대부분 사용자가 결제하지 않고 창을 닫은 정상 흐름이에요.

외부 브라우저로 열 때

내장 브라우저를 두고 싶지 않다면 DEFAULT로 받은 결제 URL을 사용자의 기본 브라우저로 열 수도 있어요(ShellExecute, Unity는 Application.OpenURL). SDK는 URL에 쿠키나 헤더, 토큰을 붙이지 않으므로 어떤 브라우저에서든 같은 결제 페이지가 열려요. Base_OpenExternalUrl은 스토브 SSO 로그인 주소로 감싸서 열므로 결제 페이지가 브라우저에 스토브 로그인 세션을 요구할 때만 쓰세요. [확인 필요] SSO 경유 후 1회용 결제 URL이 그대로 전달되는지 실측이 필요해요.

  • 외부 브라우저는 닫힘 이벤트를 게임에 전달하지 않아요. "창 닫힘 시 호출" 대신 게임 창 활성화 복귀(Win32는 WM_ACTIVATEAPP, Unity는 OnApplicationFocus)와 "결제 완료 확인" 버튼 두 곳에서 같은 확인 함수를 호출하고, 진행 중 플래그로 겹침 호출을 막으세요.
  • 첫 조회에서 status == false가 와도 거래 번호를 바로 지우지 마세요. 사용자가 아직 브라우저에서 결제 중일 수 있어요. 결제 완료로 확인됐을 때만 보관을 해제하고, 사용자가 취소를 선택하거나 새 결제를 시작할 때 정리하세요. 미완료 주문은 서버가 자체 정리해요.
  • 독점 전체화면 게임은 브라우저로 전환되는 순간 최소화될 수 있어요. 결제 중에는 창 모드나 테두리 없는 전체화면을 권해요.

스팀 배포 게임은 operation 값과 무관하게 항상 DEFAULT처럼 동작하지만, 결제창은 스팀 오버레이가 띄우므로 위 설명의 "결제창 표시" 단계는 해당하지 않아요. 스팀 결제 절을 참고하세요.

결제창 표시 방식 (webViewMode)

값표시 방식특징
WebViewMode::INTERNAL게임 메인 창의 자식 창으로 게임 화면 위에 겹쳐 그려요위치와 크기(SetWebviewRect(x, y, width, height), 픽셀)를 지정할 수 있어요. 초기화 때 IAP_InitializeWithWndInfo로 게임 창 핸들을 전달해야 하고, 자식 창을 만들 수 없으면 EXTERNAL로 동작해요
WebViewMode::EXTERNAL게임 창과 독립된 별도 창으로 그려요화면 전체를 덮는 형태라 게임 창의 표시 상태에 영향을 받지 않아요

Exclusive Fullscreen(FSE) 게임은 INTERNAL을 쓸 수 없어요. INTERNAL은 게임 화면 위에 창을 겹쳐 그리는 방식이라 Exclusive Fullscreen 모드에서는 결제창이 그려지지 않아요. EXTERNAL은 Exclusive Fullscreen 모드에서도 결제창이 표시되지만, 별도 창이 앞으로 나오면서 게임 화면이 최소화(minimize)되는 문제가 있어요. 따라서 Exclusive Fullscreen을 쓰는 게임은 결제창을 띄울 때 게임 화면을 Borderless Windowed Fullscreen으로 전환하는 방법을 권장해요.


상품 조회 결과를 구매 파라미터로 옮기기

상품 목록 조회(IAP_FetchProducts) 콜백으로 받는 StovePCProduct와 구매 요청(IAP_StartPurchase)에 담는 StovePCOrderProduct는 서로 다른 구조체라, 조회한 상품을 그대로 넘길 수 없고 필요한 값을 옮겨 담아야 해요. 옮기는 값은 아래 세 가지예요.

StovePCOrderProduct (구매 요청)가져올 값설명
SetProductIdStovePCProduct::GetProductId()플랫폼 상품 아이디예요. 그대로 옮겨요.
SetSalePriceStovePCProduct::GetSalePrice()결제용 판매가예요. 서버가 이 값을 실제 판매가와 비교하므로 그대로 옮겨요. 정가(GetPrice())나 전시용 가격(GetDisplaySalePrice() 등)을 넣으면 가격 불일치로 구매가 거부될 수 있어요.
SetQuantity이용자가 고른 구매 수량StovePCProduct::GetQuantity()는 이 상품을 1회 구매할 때 지급되는 아이템 수량이라 구매 수량이 아니에요. 복사하지 말고 이용자가 고른 수량(보통 1)을 넣어요.

구매 버튼을 누르는 시점은 조회 콜백보다 늦으므로, 콜백 인자로 받은 배열을 콜백 밖에서 쓰지 말고 상품 아이디와 판매가를 콜백 안에서 게임의 상점 모델에 복사해 두었다가 구매할 때 StovePCOrderProduct를 만들어요. 판매가는 할인 기간 등으로 바뀔 수 있으니 구매 직전에 화면에 보여 준 조회 결과의 값을 써야 해요. IAP_FetchProductsEx로 받는 StovePCProductEx도 같은 getter를 제공하므로 같은 방법으로 옮겨요. 예제의 Game::/Game. 호출과 ShopItem은 개발사가 구현하는 의사(Pseudo) 코드예요.

cpp
// 상점 모델 — 조회 콜백에서 복사해 두는 값
struct ShopItem
{
    int64_t productId;
    double  salePrice;
};

// (1) 상품 목록 조회 콜백 — 구매에 필요한 값만 복사해 둔다
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 = products[i].GetProductId();
            item.salePrice = products[i].GetSalePrice();   // 결제용 판매가 (GetPrice()·GetDisplaySalePrice() 아님)
            Game::Shop::Add(item);
        }
    });

// (2) 구매 버튼 — 보관해 둔 값과 이용자가 고른 수량으로 주문 항목을 만든다
void OnBuyClicked(const ShopItem& item, int32_t count)
{
    StovePCOrderProduct orderProduct;
    orderProduct.SetProductId(item.productId);
    orderProduct.SetSalePrice(item.salePrice);
    orderProduct.SetQuantity(count);   // 이용자가 고른 구매 수량. StovePCProduct::GetQuantity() 를 넣지 않는다

    StovePCStartPurchaseParam params;
    params.CreateOrderProduct(1);
    params.SetOrderProduct(0, &orderProduct);
    // 이후 옵션 설정과 IAP_StartPurchaseEx 호출은 아래 *샘플 코드* 의 (1)과 같아요.
}

스팀 결제

스팀런처로 배포·실행되는 게임의 결제 동선이에요. 스토브런처로만 배포한다면 이 단락은 건너뛰고 위 동선을 그대로 따르면 돼요.

이 동선은 게임이 외부플랫폼연동모듈(APIModule)로 스토브 인증을 마치고 PCSDK3가 기동된 상태를 전제로 해요. 모듈 연동과 스팀 게임 약관 동의는 스팀 연동 가이드에서 다루고, 이 단락은 그 이후의 결제 부분만 설명해요.

IAP_StartPurchase에는 스팀런처 동선과 스토브런처 동선을 구분하는 파라미터나 옵션이 없어요. 스팀 기반으로 실행했을 때 결제창(스토브런처 기능)이 뜰지 스팀 오버레이가 뜰지를 개발사가 설정하는 곳도 없어요. SDK가 동선을 고르는 기준은 외부플랫폼연동모듈 초기화 때 넘긴 스팀 유저 아이디(SteamUserId) 하나예요. 이 값이 있으면 스팀 결제 동선, 없으면(스토브런처 실행 포함) 스토브 결제창 동선으로 자동 처리되며, 현재 동선을 조회하는 API도 없어요. 스토브런처와 스팀런처를 모두 지원한다면 외부플랫폼연동모듈로 인증한 시점에 플래그를 세워 두고, IAP_ConfirmPurchase 결과는 위 스토브런처와 스팀런처를 한 가지 조건으로 판정하려면 의 공통 판정으로 읽으세요.


동선

  1. 상점 구성: IAP_FetchShopCategories로 카테고리를, IAP_FetchProducts로 상품 목록을 조회해 상점 UI를 구성해요. 여기까지는 기본 동선과 같아요.
  2. 구매 시작: 이용자가 상품을 고르면 IAP_StartPurchase를 호출해요. 상품 정보(productId·salePrice·quantity)만 채우고, StovePCPurchaseOption은 기본값 그대로 두세요.
  3. 두 가지가 동시에 일어나요: ① IAP_StartPurchase 콜백으로 거래 마스터 번호(transactionMasterNumber) 가 도착하고, ② 스팀런처가 게임 위에 스팀 결제 오버레이를 띄워요. 두 동작의 순서는 보장되지 않으니, 콜백에서 받은 거래 마스터 번호를 변수에 보관해 두세요.
  4. 이용자 결제: 이용자가 오버레이에서 구매를 승인하거나 취소해요. 이 화면은 스팀이 그리므로 개발사가 만들 UI는 없어요.
  5. 결과 수신: 승인·취소 결과는 SDK가 아니라 Steamworks의 MicroTxnAuthorizationResponse_t 콜백으로 도착해요. 콜백 등록과 처리는 게임이 연동한 Steamworks SDK 영역이에요.
  6. 구매 확정: 승인된 경우 보관해 둔 거래 마스터 번호로 IAP_ConfirmPurchase를 호출해요. 스팀 동선에는 자동 확정이 없어서 이 호출을 건너뛰면 아이템이 지급되지 않아요. 취소·미승인으로 끝난 주문은 호출하지 않아도 백엔드가 결제 취소로 정리하지만, 결과 콜백을 받지 못한 경우에는 이 호출로 최종 상태를 확인하세요.
  7. 지급 확인: IAP_FetchInventory로 지급된 아이템을 확인해요.

실제 구현 코드는 아래 샘플 코드 → 스팀 결제(스팀런처 배포 게임) 를 참고하세요. 같은 샘플 코드 안의 (1)~(3) operation 예제는 스토브 결제창 동선이므로 스팀 동선에는 해당하지 않아요.


결제 오버레이 화면

이용자가 구매를 시작하면 스팀런처가 게임 위에 아래와 같은 구매 승인 화면을 띄워요. 상품명·수량·금액은 스토브에 등록된 상품 정보를 백엔드가 스팀에 전달해 구성돼요.


기본 PC 결제와 다른 점

  • StovePCPurchaseOption은 적용되지 않아요. 어떤 값을 넣어도 DEFAULT처럼 동작하고, 결제창은 스팀 오버레이가 맡아요.
  • 결제 완료 신호는 IAP_StartPurchase 콜백이 아니라 Steamworks의 MicroTxnAuthorizationResponse_t 콜백으로 와요. SDK 콜백 러너(Base_RunCallback())와 Steamworks 콜백 펌프(SteamAPI_RunCallbacks())를 둘 다 돌려야 해요.
  • SDK 자동 확정이 없어요. 스팀 오버레이에서 승인돼도 IAP_ConfirmPurchase를 호출하지 않으면 아이템이 지급되지 않아요.
  • 결제 API 콜백 값 중 거래 마스터 번호(transactionMasterNumber)만 유효해요. 결제 URL·purchaseProgress·구매 상품 배열·과금 정보·status는 기본값으로 내려오니 참조하지 말고, CallbackResult만 보고 판정하세요. 성공이면 결제가 확정되고 아이템이 지급된 거예요. 실패이고 externalError가 22001이면 스팀 트랜잭션이 승인되지 않은 상태(취소·승인 대기·만료)라 취소로 처리하세요. 실패이고 결과 코드가 249(NETWORK_TRANSPORT_ERROR)면 네트워크 안내 후 앞 호출의 콜백을 받은 뒤에만 다시 호출하세요. 그 외 실패는 서버 또는 SDK 오류예요.
  • IAP_StartPurchase가 externalError 21107로 실패하면 완료되지 않은 이전 스팀 거래가 남아 있는 거예요. 재시도하지 말고 "이전 결제가 진행 중입니다. Steam 오버레이에서 완료하거나 취소해 주세요"를 안내하고, 직전 거래 마스터 번호가 있으면 IAP_ConfirmPurchase를 한 번 호출해 상태를 정리하세요.
  • 약관 동의(IAP_FetchTermsAgreement)는 사용하지 않아요. 스팀 게임 약관 동의는 외부플랫폼연동모듈 동선에서 처리돼요. 게임 탈퇴(IAP_WithdrawGame)는 지원하지 않아요.

스팀 콜백이 오지 않을 수 있어요
STOVE PCSDK가 아니라 Steamworks SDK 구현에서 생기는 이슈이지만, 결제 대기가 무한히 이어질 수 있어 함께 안내해요. 결제 중 네트워크가 끊긴 상태에서 이용자가 결제 창을 닫으면 GameOverlayActivated_t는 오지만 MicroTxnAuthorizationResponse_t는 오지 않아요.
ㆍ 결제 대기 중 GameOverlayActivated_t의 m_bActive가 0으로 오면 마지막 닫힘 시점부터 3~5초 안에 MicroTxnAuthorizationResponse_t가 오지 않을 때 보관해 둔 거래 마스터 번호로 IAP_ConfirmPurchase를 호출해 최종 상태를 확정하세요. 정상 취소 때는 결제 창이 닫힌 뒤 취소 확인 대화상자가 다시 열리고(m_bActive=1) 닫힌 뒤 약 2초 뒤에 콜백이 오므로, 오버레이가 다시 열리면 유예를 멈추고 닫힐 때마다 유예를 다시 재세요.
ㆍ 결제 대기 중 SteamServersDisconnected_t를 받았다면 오버레이가 닫힐 때 유예 없이 바로 IAP_ConfirmPurchase를 호출하세요. 오버레이를 끈 이용자(ISteamUtils::IsOverlayEnabled()가 거짓)는 GameOverlayActivated_t도 오지 않으니 결제 대기 화면에 직접 확인·취소할 수 있는 버튼을 두세요.
ㆍ 대기가 끝난 뒤 늦게 도착한 MicroTxnAuthorizationResponse_t도 무시하지 말고 IAP_ConfirmPurchase를 호출하세요. 이 호출은 스토브 서버로 가므로 스팀 연결 상태와 무관하게 할 수 있고, 최종 판정은 항상 이 호출의 결과로 하세요.


트러블슈팅
상황원인해결 방법
게임 진입 직후 IAP 기능이 동작하지 않아요BaseSDK 초기화(Base_Initialize)나 이용자 로그인이 끝나지 않은 상태에서 IAP API를 호출했어요.Base_Initialize 완료 후 IAP_Initialize로 IAPSDK를 초기화하고 로그인을 마친 뒤 IAP API를 호출해야 해요.
결제를 시작했는데 약관 미동의 응답이 와요스토브 결제 약관에 동의하지 않은 이용자라 결제가 차단된 상태예요. 신규 이용자나 약관 개정 직후에 자주 발생해요.약관 동의 조회 API(IAP_FetchTermsAgreement)로 약관 미동의 여부를 먼저 확인하고, 필수 약관에 미동의면 약관 동의 팝업을 띄워야 해요. 동의 완료 후 결제 흐름으로 되돌아오게 만들면 문제없어요.
상품 조회가 빈 상품 목록을 반환해요파트너스에 상품이 아직 등록되지 않았거나, 등록은 됐지만 마켓 키(상품 ID)가 게임에서 사용 중인 값과 일치하지 않아요. 빌드별로 상품 ID를 다르게 운영하다 발생하는 경우가 많아요.파트너스 빌링 콘솔에서 상품 등록 상태와 마켓 키를 확인하고, 게임 클라이언트가 동일한 상품 ID를 보내는지 확인해야 해요. 환경(개발/스테이지/라이브)별 상품 ID가 분리돼 있다면 빌드 환경과 매칭되는지 점검하면 문제없어요.
결제 진행 중에 결제 창이 갑자기 닫혀요IAP API를 새로 호출하면 기존에 떠 있던 결제·약관 창이 일괄 종료돼요. 두 개의 결제 흐름이 동시에 노출되는 것을 막기 위한 의도된 동작이에요.한 번에 하나의 IAP 흐름만 진행하도록 결제 시작 시 게임 측에서 추가 호출을 막아야 해요. 결제 종료 콜백을 받기 전까지 결제 버튼을 비활성화하면 문제없어요.
결제 결과 콜백이 호출되지 않아요게임 메인 루프에서 콜백 러너(Base_RunCallback())를 호출하지 않으면 결제 결과 이벤트가 게임에 전달되지 않아요.메인 루프에서 매 프레임 또는 일정 주기로 콜백 러너를 호출해야 해요. 결제 진행 중에는 게임 일반 루프와 동일하게 호출되고 있는지 확인하면 문제없어요.
결제는 성공했는데 게임 내에서 아이템이 지급되지 않고 스토브에 50052(아이템 발송 실패) 오류가 기록돼요결제는 스토브 → 게임 서버 결제 알림(웹훅) 전송 → 게임 서버 응답 수신 → 지급 처리로 완료돼요. 게임 서버 알림 URL 미등록·잘못된 경로, 게임 서버 응답 누락이 있으면 스토브가 통지 전송 실패로 판단해 50052 오류로 기록하고 지급이 누락돼요.파트너스 빌링 설정에서 결제 알림 URL이 정확히 등록돼 있는지 확인하고, 게임 서버는 알림 수신 직후 동기적으로 정상 응답을 회신하도록 구현해야 해요. 알림 URL과 서버 응답을 우선 점검하면 50052 오류 발생을 막을 수 있어요.
멀티캐릭터 게임에서 다른 캐릭터로 아이템이 지급돼요결제 진입 전에 게임 프로필 설정 API로 현재 캐릭터의 식별자(character_no)를 설정하지 않으면 스토브 서버가 어떤 캐릭터에게 지급해야 할지 알 수 없어요.캐릭터 선택 직후마다 게임 프로필 설정 API를 호출해 현재 캐릭터를 SDK에 갱신해야 해요. 캐릭터 변경 흐름이 있는 게임이면 변경 시점마다 다시 호출하면 문제없어요.
스팀 결제 오버레이가 뜨지 않아요Steamworks SDK가 초기화되지 않았거나, 스팀 클라이언트에서 게임 내 오버레이가 비활성화돼 있거나, 파트너스에 등록된 스팀 마켓 정보가 실제 앱과 달라요.Steamworks SDK 초기화와 스팀 클라이언트의 오버레이 설정을 먼저 확인하고, 파트너스 빌링에 등록된 스팀 마켓 정보가 실제 앱과 일치하는지 대조하면 문제없어요.
스팀 오버레이에서 결제를 승인했는데 게임이 아무 반응이 없어요Steamworks 콜백 펌프(SteamAPI_RunCallbacks())가 돌지 않아 MicroTxnAuthorizationResponse_t가 게임에 전달되지 않았어요.게임 루프에서 SteamAPI_RunCallbacks()를 호출해야 해요. SDK 콜백 러너(Base_RunCallback())와는 별개라 둘 다 돌고 있는지 확인하면 문제없어요.
스팀 결제는 성공했는데 아이템이 지급되지 않아요스팀 동선에는 SDK 자동 구매 확정이 없는데 IAP_ConfirmPurchase를 호출하지 않았어요.MicroTxnAuthorizationResponse_t에서 승인 결과를 받은 뒤 반드시 IAP_ConfirmPurchase를 호출해야 해요.
구매를 확정하려는데 거래 마스터 번호가 없어요IAP_StartPurchase 콜백과 스팀 오버레이 노출은 순서가 보장되지 않는데, 콜백에서 받은 거래 마스터 번호를 보관하지 않았어요.IAP_StartPurchase 콜백에서 거래 마스터 번호를 변수에 보관해 두고, Steamworks 콜백 시점에 꺼내 쓰면 문제없어요.
스팀 결제 오버레이가 열린 채 네트워크가 끊겼다가 복구된 뒤 취소하면 게임이 멈춰요Steamworks가 MicroTxnAuthorizationResponse_t를 전달하지 않았는데 게임이 이 콜백만 기다리고 있어요.GameOverlayActivated_t로 오버레이 닫힘을 감지해 IAP_ConfirmPurchase를 호출하고, externalError가 22001이면 취소로 처리하면 문제없어요.
IAP_StartPurchase가 externalError 21107로 실패해요완료되지 않은 이전 스팀 거래가 남아 있어요.이용자에게 Steam 오버레이에서 이전 거래를 완료하거나 취소하도록 안내하고, 직전 거래 마스터 번호로 IAP_ConfirmPurchase를 호출해 상태를 정리하면 문제없어요.

결제 종료 이벤트가 필요하면 Ex 버전을 사용해요
IAP_StartPurchase, IAP_StartPayment 등은 결제 시작 결과만 전달해요. 팝업 닫힘 시점에 게임 흐름을 재개해야 한다면 Ex 버전(IAP_StartPurchaseEx, IAP_StartPaymentEx, IAP_FetchTermsAgreementEx, IAP_FetchProductsEx)을 호출해 종료 이벤트를 받으세요.

결제 유효성 검증은 게임 서버에서 수행해요
클라이언트의 구매 확정(IAP_ConfirmPurchase)만으로는 위변조 방지가 보장되지 않아요. 게임 서버는 결제 알림 수신 후 스토브 결제 유효성 체크 API로 2차 검증한 뒤 재화/아이템을 지급해야 해요.


샘플 코드

각 기능을 함수 단위로 나눠 예제를 제공해요. 전체 결제 동선은 초기화·약관 → 상점 구성 → 구매 → 검증 → 보관함 순서로 진행해요. 예제의 Game::/Game. 호출은 개발사가 구현하는 의사(Pseudo) 함수예요.

초기화와 종료

Base_Initialize 완료 후 IAP_Initialize(shopKey)(부모 창이 필요하면 IAP_InitializeWithWndInfo)로 IAPSDK를 초기화해요. 종료 시에는 IAP_UnInitialize를 호출한 뒤 Base_UnInitialize로 정리해요.

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();

약관 동의

초기화 후에는 IAP_FetchTermsAgreement로 필수 약관 동의 여부를 먼저 확인해요. 미동의 시 약관 동의 흐름(전달된 URL 또는 SDK 웹뷰)을 노출해요.

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)
        {
            // 약관 동의 흐름을 노출해 주세요.
        }
    });

상점 구성

카테고리 조회(IAP_FetchShopCategories)로 상점 탭을, 상품 목록 조회(IAP_FetchProducts)로 각 카테고리의 아이템 목록을 가져와 UI를 구성해요. 카테고리 ID를 빈 값으로 전달하면 전체 범위에서 조회돼요.

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 구성
        }
    });

인게임 아이템 구매

구매는 IAP_StartPurchase/IAP_StartPurchaseEx로 시작해요. 아래 (1)이 권장 예제이고, (2)와 (3)은 (1)과 달라지는 부분만 보여 줘요. 동작 원리와 판정 기준은 위 구매 옵션과 결제창 표시 방식 을 참고하세요.

(1) WITH_WEBVIEW_AND_CONFIRM_RESULT — 결제창 표시 + 구매 검증 자동 (권장)

SDK가 결제창 표시, 결제 완료 감지, 구매 확정까지 처리하고 결과를 onFinished로 전달해요. IAP_ConfirmPurchase를 직접 호출하면 중복 확정이 되니 호출하지 마세요.

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) 상품 구성 — 사용자가 선택한 인게임 아이템 정보
    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);            // 주문 상품 개수만큼 내부 배열 생성
    params.SetOrderProduct(0, &product1);
    params.SetOrderProduct(1, &product2);

    // (2) 옵션 — SDK 결제창 + 자동 확정. SetWebviewRect(x, y, width, height), 정중앙은 (-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);   // 결제 진행 중 중복 클릭 방지

    // (3) 결제 시작 — 결제창 닫힘(onDestroy)을 받기 위해 Ex 버전 사용
    IAP_StartPurchaseEx(&params,
        // onFinished: SDK가 ConfirmPurchase 까지 끝낸 뒤 1회 호출되는 구매 완료 처리 지점
        [](CallbackResult callbackResult, StovePCPurchaseResult purchaseResult)
        {
            if (!callbackResult.GetResult().IsSuccessful())
            {
                // 결제 실패/취소. WEBVIEW_CLOSED_BEFORE_PURCHASE 면 사용자가 결제 전에 창을 닫은 취소(오류 아님),
                // 그 외는 결제창 진입 실패·파라미터 오류·네트워크/서버 오류. 어느 경우든 지급 없음.
                return;
            }

            if (!purchaseResult.IsPurchased())
            {
                // 호출은 성공했으나 서버가 결제 완료를 확인하지 않은 미확정 상태(드묾). 지급하지 않고 재조회 또는 고객지원으로 넘긴다.
                return;
            }

            // 구매 완료 — 여기서만 지급한다. transactionMasterNumber 는 거래마다 고유하므로 중복 지급 방지 키로 쓴다.
            for (uint32_t i = 0; i < purchaseResult.GetPurchasedProductCount(); ++i)
            {
                const StovePCPurchasedProduct* product = purchaseResult.GetPurchasedProduct(i);
                int64_t productId = product->GetProductId();          // 플랫폼 상품 아이디
                int64_t detailNo  = product->GetTransactionDetailNumber();   // 구매 상세 번호
                // 구매한 아이템 별로 지급 처리
            }
            for (uint32_t i = 0; i < purchaseResult.GetChargeInfoCount(); ++i)
            {
                const StovePCChargeInfo* charge = purchaseResult.GetChargeInfo(i);
                int32_t type     = charge->GetChargeType();        // 98:STOVE 캐시, 99:포인트, 그 외:PG 결제 수단
                double deductVal = charge->GetChargeDeductVal();   // 결제 가격
                // 영수증 표시·정산 로깅 등
            }
        },
        // onDestroy: 결제창이 닫혔을 때. UI 정리 전용 (완료 판정과 지급은 onFinished 에서)
        [](CallbackResult callbackResult)
        {
            Game::ShopUI::SetPurchaseButtonEnabled(true);
        });
}

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

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

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

IAP_StartPurchaseEx(&params,
    // onFinished: 결제 URL 발급 시점 (구매 완료 아님)
    [](CallbackResult callbackResult, StovePCPurchaseResult purchaseResult)
    {
        if (!callbackResult.GetResult().IsSuccessful())
            return;   // 주문 생성 실패. 안내 후 종료

        int64_t txnNo = purchaseResult.GetTransactionMasterNumber();
        Game::SavePendingTransaction(txnNo);   // 거래 번호 보관(비정상 종료 대비 로컬 저장 권장)

        if (purchaseResult.GetPurchaseProgress() == PurchaseProgress::NOT_NEED_PAYMENT_WINDOW)
        {
            IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);   // 0원 결제: 창 없이 바로 확정
            return;
        }

        Game::OpenOwnPaymentPage(purchaseResult.GetOneTimePaymentUrl(), txnNo);   // 게임이 결제창 표시
    },
    [](CallbackResult callbackResult) {});   // onDestroy: DEFAULT 는 SDK 결제창이 없어 호출되지 않음

// 게임이 띄운 결제창이 닫히는 시점에 호출. 미확정이면 5초 뒤 1회 재조회
void Game_ConfirmOwnPurchase()
{
    int64_t txnNo = Game::PeekPendingTransaction();
    if (txnNo != 0)
        IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);
}

// 구매 확정 결과 — 판정은 위 JudgeConfirmPurchase 와 같다
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(); /* purchasedProducts 로 지급 */ break;
    case ConfirmOutcome::Pending:   /* 지급 금지. 거래 번호 유지, 재조회 또는 결제 확인 버튼 */   break;
    case ConfirmOutcome::Failed:    /* 지급 금지. 실패 안내 */                                   break;
    }
}

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

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

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: 결제창 표시 시점 (구매 완료 아님). 0원 결제 분기와 거래 번호 보관은 (2)와 같다
    [](CallbackResult callbackResult, StovePCPurchaseResult purchaseResult) { /* (2)와 동일 */ },
    // onDestroy: 결제창 닫힘. UI 정리만 하고 ConfirmPurchase 는 호출하지 않는다
    [](CallbackResult callbackResult)
    {
        Game::ShopUI::SetPurchaseButtonEnabled(true);
    });

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

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

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

static int64_t  g_PendingTxnNo = 0;      // 스팀 결제 결과를 기다리는 주문
static int64_t  g_LastTxnNo = 0;         // 이번 구매의 거래 마스터 번호(늦게 온 스팀 콜백·재시도용)
static int64_t  g_ConfirmingTxnNo = 0;   // IAP_ConfirmPurchase 진행 중인 주문(겹침 호출 방지)
static uint64_t g_GraceDeadlineMs = 0;   // 오버레이 닫힘 뒤 스팀 콜백을 기다리는 유예 만료 시각(0 이면 없음)

// (1) 구매 시작 — StartPurchase 콜백과 오버레이 노출은 순서가 보장되지 않으므로 거래 마스터 번호를 보관한다
void StartSteamPurchase()
{
    StovePCOrderProduct product; product.SetProductId(123); product.SetSalePrice(1000); product.SetQuantity(1);
    StovePCStartPurchaseParam params;
    params.CreateOrderProduct(1);
    params.SetOrderProduct(0, &product);   // StovePCPurchaseOption 은 기본값 그대로

    Game::ShopUI::SetPurchaseButtonEnabled(false);
    IAP_StartPurchase(&params,
        [](CallbackResult callbackResult, StovePCPurchaseResult purchaseResult)
        {
            if (!callbackResult.GetResult().IsSuccessful())
            {
                Game::ShopUI::SetPurchaseButtonEnabled(true);
                if (callbackResult.GetExternalError() == 21107)
                {
                    // 완료되지 않은 이전 스팀 거래가 남아 있음 — 재시도하지 말고 안내한 뒤 직전 주문 상태를 정리한다
                    Game::ShopUI::ShowMessage(L"이전 결제가 진행 중입니다. Steam 오버레이에서 완료하거나 취소해 주세요.");
                    ConfirmPendingPurchase(g_LastTxnNo);
                }
                return;
            }
            g_PendingTxnNo = g_LastTxnNo = purchaseResult.GetTransactionMasterNumber();   // 유효한 값은 이 번호뿐
        });
}

// (2) 스팀 결제 결과 — Steamworks MicroTxnAuthorizationResponse_t 콜백에서 호출
void OnSteamMicroTxnAuthorized(bool authorized)
{
    int64_t txnNo = g_PendingTxnNo;
    g_PendingTxnNo = 0;
    g_GraceDeadlineMs = 0;
    if (txnNo == 0 && authorized) txnNo = g_LastTxnNo;   // 유예 경로에서 확정을 시작한 뒤 늦게 온 승인이면 다시 확인

    if (!authorized || txnNo == 0)
    {
        Game::ShopUI::SetPurchaseButtonEnabled(true);   // 취소·미승인 — 지급 없음. 미확정 주문은 백엔드가 정리
        return;
    }
    ConfirmPendingPurchase(txnNo);
}

// (3) 스팀 콜백이 오지 않을 때 — GameOverlayActivated_t 콜백에서 호출. 닫힐 때마다 유예 3초를 다시 재고, 다시 열리면 멈춘다
void OnSteamOverlayActivated(bool active)
{
    if (g_PendingTxnNo == 0) return;
    g_GraceDeadlineMs = active ? 0 : (Game::Clock::NowMs() + 3000);
    // 결제 대기 중 SteamServersDisconnected_t 를 받았다면 유예 없이 바로 ConfirmPendingPurchase(g_PendingTxnNo)
}

void TickPurchaseWait()   // 게임 루프에서 매 프레임 호출
{
    if (g_GraceDeadlineMs == 0 || Game::Clock::NowMs() < g_GraceDeadlineMs) return;
    g_GraceDeadlineMs = 0;
    int64_t txnNo = g_PendingTxnNo;
    g_PendingTxnNo = 0;
    ConfirmPendingPurchase(txnNo);   // 유예가 끝났는데 스팀 콜백이 없으면 ConfirmPurchase 로 최종 상태 확정
}

// (4) 구매 확정 — 스팀 동선에는 자동 확정이 없다. 앞 호출의 콜백을 받은 뒤에만 호출한다
void ConfirmPendingPurchase(int64_t txnNo)
{
    if (txnNo == 0 || g_ConfirmingTxnNo != 0) return;
    g_ConfirmingTxnNo = txnNo;
    IAP_ConfirmPurchase(txnNo, OnConfirmPurchase);
}

// status·purchasedProducts·chargeInfos 는 기본값으로 오므로 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;   // 스팀 트랜잭션 미승인(취소·대기·만료) — 취소로 처리
        if (callbackResult.GetResult().GetResultCode() == (uint32_t)Base::SDKResultCode::NETWORK_TRANSPORT_ERROR)
            Game::ShopUI::ShowNetworkRetry([txnNo]() { ConfirmPendingPurchase(txnNo); });   // 네트워크 안내 후 재시도
        return;   // 그 외 실패 — 지급 금지
    }

    // 확정 완료 — 지급 결과는 보관함 조회로 확인한다
    IAP_FetchInventory([](CallbackResult cb, StovePCInventoryItem* items, uint32_t itemsSize) { /* 보관함 UI 갱신 */ });
}

구매 검증

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

cpp
IAP_ConfirmPurchase(transactionMasterNumber,
    [](CallbackResult callbackResult, bool status,
       StovePCPurchasedProduct* purchasedProducts, uint32_t purchasedProductsSize,
       StovePCChargeInfo* chargeInfos, uint32_t chargeInfosSize)
    {
        if (JudgeConfirmPurchase(callbackResult, status) == ConfirmOutcome::Confirmed)
        {
            // 게임 서버 2차 검증 후 아이템 지급 처리
        }
    });

보관함 조회

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

cpp
IAP_FetchInventory(
    [](CallbackResult callbackResult, StovePCInventoryItem* inventoryItems, uint32_t inventoryItemSize)
    {
        if (callbackResult.GetResult().IsSuccessful())
        {
            // inventoryItems[0..inventoryItemSize) 로 보관함 UI 구성
        }
    });

게임 탈퇴와 팝업 정리

게임 탈퇴(약관 철회) UI는 IAP_WithdrawGame으로 표시해요. 열린 IAP 결제 창을 즉시 모두 닫아야 할 때는 IAP_CloseAllPopups를 호출해요.

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();

서버 연동

사전 준비

  • 정상적인 빌링 동작을 위해 파트너스에 아래 정보를 모두 등록해야 해요.
구분 파트너스 메뉴 위치 항목 내용
빌링 연동 정보 [파트너스] > [퍼블리싱 센터] > [기본 빌링 설정 관리] > [빌링 연동 정보 관리] 결제 완료 알림 URL 결제 완료 후 결제 정보 전달 받을 게임서버 URL
환불 내역 알림 URL 마켓의 환불 정보 수신 후 전달 받을 게임서버 URL
아이템 회수 알림 URL 마켓의 환불 요청을 승인 판단 시 아이템 회수 처리 할 게임서버 URL
  • 플랫폼 서버와 게임서버간 통신 확인
    • 플랫폼 서버와 게임서버간 통신확인이 필요해요.
    • 결제 완료 알림 수신 시 결제 유효성 체크 API 연동으로 결제 완료 유효성 체크가 필요해요.

개발 흐름

  1. SDK 연동으로 전달 받은 아이템 목록에서 결제 요청을 진행해요.
  2. 결제 요청 후 결제를 진행하면 SDK를 통해서 빌링 서버로 결제정보가 전달돼요.
  3. 빌링 서버에서는 결제 정보의 유효성을 판단한 후 결제 완료 알림 URL에 등록된 게임서버로 결제 완료 정보를 전달해요.
  4. 게임서버에서는 결제 정보 유효성 API를 확인한 후 아이템 지급 후 빌링 서버에 응답을 해줘요.

ACL 설정

  • STOVE 서비스는 별도 Outbound 제한 정책은 없습니다.
  • 만약 '게임서버장비’에서 Inbound ACL 정책 제어가 필요한 경우라면, 기능 테스트 등을 통한 게임내 연결 검증을 필히 권장 드립니다.
빌링 (미들웨어) ACL 설정
환경NAT IP
SandBox52.193.143.11
52.196.37.103
52.197.65.49
54.248.156.218
Live52.69.38.53
52.192.82.246
13.113.43.215
3.113.195.187
52.197.237.44
빌링 (STMo) , ItemBox ACL 설정
환경NAT IP
SandBox52.198.86.83
18.176.44.28
18.180.119.9
Live52.198.86.83
52.192.238.228

비정상 환불 대응

1단계: 환불 검토 및 아이템 회수

이용자가 마켓에 환불을 요청하면, 마켓이 환불을 확정하기 전에 스토브 빌링이 결제건의 소비·회수 상태를 마켓에 회신해 환불 어뷰징(이미 소비·판매한 상품의 환불)을 막아요. 이 단계의 마켓 회신(Apple Send Consumption Information / Google orders.reviewrefund)은 스토브 빌링이 자체적으로 처리하며, 게임 서버는 환불요청이 전달되어 호출되는 아이템 회수 요청 API만 구현하면 돼요.


마켓별 동작 방식

구분애플 (App Store)구글 (Google Play)
환불정보 수신 방식App Store Server Notifications V2 (SSN)Real-time Developer Notifications (RTDN, Cloud Pub/Sub)
수신 노티 타입CONSUMPTION_REQUESTpendingRefundReviewNotification
스토브 빌링의 응답 APISend Consumption Informationorders.reviewrefund
스토브 빌링의 응답 제한시간12시간48시간

응답 제한시간은 스토브 빌링 기준이에요
애플 12시간·구글 48시간은 스토브 빌링이 마켓에 소비 정보를 회신해야 하는 기한으로, 게임 서버가 별도로 대응할 부분은 없어요. 게임 서버는 아래 아이템 회수 요청 API만 정상 응답하면 돼요.


처리 흐름

아이템 회수 요청 API 응답 규격


게임 서버 구현 API

게임 서버는 아래 API를 구현해야 해요. (파트너스 > 빌링 설정에 등록하는 "아이템 회수 알림 URL"이 여기에 대응돼요.)

필드값설명
item_statusint아이템 회수 결과: 0 회수완료 / 1 회수못함
2단계: 환불 재결제

1단계(환불 검토)에서 거부 의견을 회신했음에도 마켓이 이를 반영하지 않고 환불을 강행 처리한 경우, 또는 애초에 1단계 대응이 불가능한 마켓(Steam)에서 환불이 발생한 경우에 적용돼요. 해당 거래는 비정상 환불로 간주되어, 이용자는 다음 게임 접속 시 해당 금액을 재결제해야 정상 이용이 가능해요.

마켓별 재결제 동작

환불이 발생한 마켓구글 출시버전(모바일)애플 출시버전(모바일)스팀 클라이언트스토브 PC 클라이언트
구글에서 환불재결제 화면 노출이용 제한 안내이용 제한 안내이용 제한 안내
애플에서 환불이용 제한 안내재결제 화면 노출이용 제한 안내이용 제한 안내
스팀에서 환불이용 제한 안내이용 제한 안내재결제 화면 노출이용 제한 안내
환불 내역 없음정상 진입정상 진입정상 진입정상 진입

재결제 화면·이용 제한 안내를 띄우는 시점은 게임마다 다를 수 있어요
로그인 성공 후, 월드 진입 후, 캐릭터 선택 시, 상점 진입 시, 구매 시도 시 등 운영 의도에 맞는 시점에 노출하면 돼요.

처리 흐름 — 접속 시 대상 여부 확인

처리 흐름 — 재결제 결제 진행 (모바일)

처리 흐름 — 재결제 결제 진행 (Steam)

이용 제한 안내 예시

게임 이용 제한 안내
마켓(Google, Apple, Steam 등)에서 환불하신 상품으로 인해 일시적으로 게임 이용이 제한되었어요. 환불하신 마켓의 게임에 접속해 해당 상품을 재결제하신 후 게임을 이용하실 수 있어요.
고객센터 문의   닫기
재결제 UI 구성 가이드

기존 재결제 기본제공 화면을 개발사에 가이드로 제공해요. 실제 게임별 디자인과 콘텐츠 구성은 각 개발사가 직접 진행해요. 아래는 재결제 화면 구성 예시예요.
구성 예시

1) 타 마켓에는 환불 건이 없고, 현재 접속한 마켓만 환불 재결제 건이 있는 경우

재결제 화면 예시 - 현재 마켓만 환불 건 있음

2) 타 마켓에 환불 건이 더 있는 경우

재결제 화면 예시 - 타 마켓에도 환불 건 있음

화면 구성 요소

구성 요소설명연동
안내 문구각 게임에 맞추어 구성-
재결제 버튼상품 결제 화면 노출SDK startPurchase 함수 호출
결제 가이드
고객센터 문의 버튼문의하기로 이동SDK customerSupport 함수 호출
SDK UI 가이드
새로고침 버튼재결제 대상 상품 목록 새로 고침-
  • 안내 문구: 각 게임에 맞추어 구성
  • 재결제 버튼: SDK의 startPurchase 함수 호출로 상품 결제 화면 노출
  • 고객센터 문의 버튼: SDK의 customerSupport 함수 호출로 문의하기 이동
  • 새로고침 버튼: 재결제 대상 상품 목록 새로고침

트러블슈팅

상황 원인 해결 방법
결제 완료 후 아이템 지급이 실패해요 결제 완료 알림 URL로 빌링 서버에서 호출이 오지 않아요. 게임서버와 빌링 서버간 네트워크 확인이 필요해요.
결제 완료 후 마켓 검증이 실패해요. 마켓별 설정 정보를 잘못 입력할 경우 발생해요. 파트너스를 통해서 마켓 검증 정보를 수정한 후 최대 1시간 후에 다시 확인이 필요해요.

샘플 코드

결제 완료 알림 처리

Method

  • POST

URL

  • 결제 완료 후 결제 정보 전달 받을 게임서버 URL

Request Body

  • Body
NameTypeRequiredDefault ValueExampleDescription
service_idStringY-STOVE_XPFWMS게임 코드
bill_platform_typeStringY-SHOP결제 유효성 체크 플랫폼 타입
  • MOBILE : 모바일 빌링
  • SHOP : 상점(온라인 빌링)
noti_typeStringY-ONLINE_PURCHASEnotification 구분
  • ONLINE_PURCHASE : 온라인일반상품 구매
  • ONLINE_CART_PURCHASE : 온라인장바구니상품 구매
  • STEAM : 스팀 구매
  • ONLINE_SUBSCRIPT : 온라인 구독 상품 구매
  • STEAM_SUBSCRIPT : 스팀 구독 상품 구매
  • IAP_PURCHASE : 모바일 일반상품 구매
  • IAP_SUBSCRIPT : 모바일 구독상품 구매
  • IAP_OOAP : 모바일 OOAP 상품 구매
world_idStringY-world_1월드(서버) 구분
guidStringN-"1234567890"스토브 회원 GUID
member_noNumberN-1234567891회원 번호
character_noNumberN-1234567892게임 캐릭터 번호
country_cdStringN-"KR"가입 국가
ageStringN-"10"회원 나이
txn_timeStringY-"1793663058725"결제 시각(Unix Timestamp, UTC+0 기준)
extra_dataStringN--요청 추가 데이터(json string)
billstore_sync_flagbooleanNfalseY상점 동기화 여부
- 게임 사 전달 되는 Body에서 제외
subscription_noStringN-"1004"온라인 구독 상품 또는 스팀 구독 상품 관련 자동결제 구독 번호

Data ( 온라인 일반 상품 (PC 인게임), 스팀)

NameTypeRequiredDefault ValueExampleDescription
tidStringY--스토브 빌링에서 발급한 주문번호
product_idStringY--스토브 플랫폼에 등록한 상품 코드
quantityNumberN--개별 구매 상품 수량
- 스토브게임 : Required: Y
- 스토어 게임 : 2개 이상 구매 시 Required: Y
product_currencyStringY-KRW, USD해당 금액의 통화
product_priceNumberY-1100, 0.99스토브 플랫폼에 등록한 상품 금액
inservice_item_idStringY--게임내 아이템ID
service_order_idStringN--서비스 주문 번호
stove_charge_infosListY--충전 창 재화 사용 내역
stove_charge_infos[].charge_deduct_valNumberN--충전 가격
stove_charge_infos[].charge_display_deduct_valNumberN--충전 노출 가격
stove_charge_infos[].charge_typeNumberN--결제 수단 코드
stove_charge_infos[].charge_type_nameStringN--결제 수단 명
text
{
    "service_id": "STOVE_XPFWMS",
    "bill_platform_type": "SHOP",
    "noti_type": "ONLINE_PURCHASE",
    "world_id": "world_1",
    "guid": "1234567890",
    "character_no": "1234567891",
    "member_no": 1234567892,
    "txn_time" : "1793663021547",
    "extra_data": "",
    "billstore_sync_flag": false,
    "country_cd": "KR",
    "age": "0",
    "data": {
        "tid": "1234567890",
        "product_id": "1004",
        "product_currency": "KRW",
        "product_price": 110000,
        "inservice_item_id": "1004",
        "service_order_id": "",
        "quantity": 1,
        "stove_charge_infos": [
            {
                "charge_deduct_val": 110000,
                "charge_display_deduct_val": 110000,
                "charge_type": 4,
                "charge_type_name": "신용카드"
            },
            {
                "charge_deduct_val": 0,
                "charge_display_deduct_val": 0,
                "charge_type": 98,
                "charge_type_name": "STOVECASH"
            },
            {
                "charge_deduct_val": 0,
                "charge_display_deduct_val": 0,
                "charge_type": 99,
                "charge_type_name": "STOVE_MILEAGE"
            },
            {
                "charge_deduct_val": 0,
                "charge_display_deduct_val": 0,
                "charge_type": 255,
                "charge_type_name": "GAMEPOINT"
            }
        ]
    }
}

Data ( 온라인장바구니상품)

NameTypeRequiredDefault ValueExampleDescription
tidStringY--스토브 빌링에서 발급한 주문번호
stove_charge_infosListY--충전 창 재화 사용 내역
stove_charge_infos[].charge_deduct_valNumberN--충전 가격
stove_charge_infos[].charge_display_deduct_valNumberN--충전 노출 가격
stove_charge_infos[].charge_typeNumberN--결제 수단 코드
stove_charge_infos[].charge_type_nameStringN--결제 수단 명
productsListY--상품정보
products[].tidStringY-1234567880스토브 빌링에서 발급한 상품 주문번호
products[].product_idStringY--스토브 플랫폼에 등록한 상품 코드
products[].quantityNumberN--개별 구매 상품 수량
- 스토브게임 : Required: Y
- 스토어 게임 : 2개 이상 구매 시 Required: Y
products[].product_currencyStringY-KRW, USD해당 금액의 통화
products[].product_priceNumberY-1100, 0.99스토브 플랫폼에 등록한 상품 금액
products[].inservice_item_idStringY--게임내 아이템ID
products[].service_order_idStringN--서비스 주문 번호
text
{
    "service_id": "STOVE_XPFWMS",
    "bill_platform_type": "SHOP",
    "noti_type": "ONLINE_CART_PURCHASE",
    "world_id": "world_1",
    "guid": "1234567890",
    "character_no": "1234567891",
    "member_no": 1234567892,
    "txn_time" : "1793663021547",
    "extra_data": "",
    "billstore_sync_flag": false,
    "country_cd": "KR",
    "age": "0",
    "data": {
        "tid": "1234567890",
        "products": [
            {
                "tid": "1234567891",
                "product_id": "1004",
                "quantity": 1,
                "product_currency": "KRW",
                "product_price": 0,
                "inservice_item_id": "1004_free",
                "service_order_id": ""
            }
        ],
        "stove_charge_infos": [
            {
                "charge_deduct_val": 110000,
                "charge_display_deduct_val": 110000,
                "charge_type": 4,
                "charge_type_name": "신용카드"
            },
            {
                "charge_deduct_val": 0,
                "charge_display_deduct_val": 0,
                "charge_type": 98,
                "charge_type_name": "STOVECASH"
            },
            {
                "charge_deduct_val": 0,
                "charge_display_deduct_val": 0,
                "charge_type": 99,
                "charge_type_name": "STOVE_MILEAGE"
            },
            {
                "charge_deduct_val": 0,
                "charge_display_deduct_val": 0,
                "charge_type": 255,
                "charge_type_name": "GAMEPOINT"
            }
        ]
}

Data ( 온라인/스팀 구독 상품)

NameTypeRequiredDefault ValueExampleDescription
tidStringY--스토브 빌링에서 발급한 주문번호
product_idStringY--스토브 플랫폼에 등록한 상품 코드
quantityNumberN--개별 구매 상품 수량
- 스토브게임 : Required: Y
- 스토어 게임 : 2개 이상 구매 시 Required: Y
product_currencyStringY-KRW, USD해당 금액의 통화
product_priceNumberY-1100, 0.99스토브 플랫폼에 등록한 상품 금액
inservice_item_idStringY--게임내 아이템ID
service_order_idStringN--서비스 주문 번호
stove_charge_infosListY--충전 창 재화 사용 내역
stove_charge_infos[].charge_deduct_valNumberN--충전 가격
stove_charge_infos[].charge_display_deduct_valNumberN--충전 노출 가격
stove_charge_infos[].charge_typeNumberN--결제 수단 코드
stove_charge_infos[].charge_type_nameStringN--결제 수단 명
text
{
    "service_id": "STOVE_XPFWMS",
    "bill_platform_type": "SHOP",
    "noti_type": "ONLINE_PURCHASE",
    "world_id": "world_1",
    "guid": "1234567890",
    "character_no": "1234567891",
    "member_no": 1234567892,
    "txn_time" : "1793663021547",
    "extra_data": "",
    "billstore_sync_flag": false,
    "country_cd": "KR",
    "age": "0",
    "subscription_no" : 1004,
    "data": {
        "tid": "1909091033503333452",
        "product_id": "test_1",
        "product_price": 5000.0,
        "product_currency": "KRW",
        "inservice_item_id": "test_1",
        "service_order_id": "testtest_1234",
        "stove_charge_infos": [
            {
                "charge_deduct_val": 15000,
                "charge_display_deduct_val": 15000,
                "charge_type": 1,
                "charge_type_name": "POQ 캐시비"
            },
            {
                "charge_deduct_val": 8100.0,
                "charge_display_deduct_val": 8100.0,
                "charge_type": 98,
                "charge_type_name": "스토브 캐시"
            },
            {
                "charge_deduct_val": 8100.0,
                "charge_display_deduct_val": 8100.0,
                "charge_type": 99,
                "charge_type_name": "포인트"
            },
            {
                "charge_deduct_val": 8100.0,
                "charge_display_deduct_val": 8100.0,
                "charge_type": 2,
                "charge_type_name": "쿠폰"
            }
        ]
}

Data ( 모바일 일반상품 / OOAP 상품)

NameTypeRequiredDefault ValueExampleDescription
tidStringY--스토브 빌링에서 발급한 주문번호
pay_typeStringY--결제 구분
- 일반 : INAPP
- OOAP_PROMO : 프로모션 코드 결제
- OOAP_POINT : 포인트 결제
market_codeStringY-APPLE_APP_STORE, GOOGLE_PLAY, HUAWEI_APP_GALLERY, ONE_STORE마켓 코드
market_product_idStringY--마켓에 등록된 상품의 코드
product_idStringY--스토브 플랫폼에 등록한 상품 코드
product_currencyStringY-KRW, USD해당 금액의 통화
product_priceStringY-KRW, USD해당 금액의 통화
price_on_marketStringY-KRW, USD해당 금액의 통화
currency_on_marketStringY-KRW, USD해당 금액의 통화
product_price_tierStringY-1해당 상품에 설정된 tier번호
inservice_item_idStringN--게임 내 아이템ID
service_order_idStringN--결제요청시 결제(IAP) 서버에 전달한 게임 payload(현재 미지원 Spec)
voided_tidStringN--환불 TID
supply_itemsArrayN--상품구매시 지급해야할 아이템 정보(재화 정보 제외)
supply_items[].service_item_codeStringY--아이템 코드번호
supply_items[].total_amountStringY--지급 수량
- 최소 1이상
supply_items[].item_descStringN--아이템 부가정보/설명
text
{
    "service_id": "STOVE_XPFWMS",
    "bill_platform_type": "MOBILE",
    "noti_type": "IAP_PURCHASE",
    "character_no": "1234567891",
    "guid": "1234567891",
    "world_id": "world_1",
    "txn_time" : 1644807685000,
    "data": {
        "tid": "1234567890",
        "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_1004",
                        "total_amount": 2,
                        "item_desc": "potion"
               }]
        }
}    

  • Response
NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0응답 코드
messageStringY-성공응답 메시지
dataObjectN{}{}응답 데이터

text
{
  "code": 0,
  "message": "OK",
  "data": {}
}
결제 유효성 체크
  • 결제 유효성 체크

Request

text
curl --location --request GET 'https://api.onstove.com/bill-cpm/v1.0/payment/{service_id}/detail?bill_platform_type={bill_platform_type}&guid={guid}&noti_type={noti_type}&tid={tid}' \
--header 'Authorization: Bearer {server_token}' \
--header 'caller-id: {caller-id}'

Parameter (Path)

NameTypeRequiredDefault ValueExampleDescription
service_idStringY-STOVE_XPFWMS서비스 아이디

Parameter (Query String)

NameTypeRequiredDefault ValueExampleDescription
bill_platform_typeStringY-MOBILE결제 유효성 체크 플랫폼 타입
- MOBILE
-SHOP
noti_typeStringY-IAP_PURCHASE구분
- ONLINE_PURCHASE : 온라인일반상품 구매
-ONLINE_CART_PURCHASE: 온라인장바구니상품 구매
-IAP_PURCHASE: 모바일 일반상품 구매
-IAP_SUBSCRIPT : 모바일 구독상품 구매
-IAP_OOAP
-IAP_PURCHASE: 모바일 OOAP 상품 구매
guidStringN--스토브 회원 GUID
- guid가 없는 게임을 제외하고는 필수
member_noNumberN--회원 번호
- guid 가 없는 게임의 경우에만 필수

Response

NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0응답 코드
messageStringY-OK응답 메시지
dataObjectN--응답 값

data (온라인 상품, 모바일 상품)

NameTypeRequiredDefault ValueExampleDescription
tidStringY-1234567890스토브 빌링에서 발급한 상품 주문번호
product_idStringY-p1004스토브 플랫폼에 등록한 상품 코드
quantityNumberN120개별 상품 수량
product_priceStringY-1100, 0.99거래 금액
product_currencyStringY-KRW, USD해당 금액의 통화
txn_timeNumberY-1644489139000결제 시각(Unix Timestamp, UTC+0 기준)
inservice_item_idStringY-cp1004게임내 아이템ID

data (온라인 장바구니 상품)

NameTypeRequiredDefault ValueExampleDescription
tidStringY-1234567890스토브 빌링에서 발급한 장바구니 주문번호
productsArrayY--상품정보
products[].tidStringY-1234567880스토브 빌링에서 발급한 상품 주문번호
products[].product_idStringY-p1004스토브 플랫폼에 등록한 상품 코드
products[].quantityNumberN11개별 상품 수량
products[].product_priceStringY-1100, 0.99거래 금액
products[].product_currencyStringY-KRW, USD해당 금액의 통화
products[].txn_timeNumberY-1644489139000결제 시각(Unix Timestamp, UTC+0 기준)
products[].inservice_item_idStringY-cp1004게임내 아이템ID

온라인 상품

text

{
  "code": 0,
  "message": "OK",  
  "data": {
    "tid": "1234567890",
    "product_id": "p_1004",
    "quantity": 2,
    "product_price": 1004,
    "product_currency": "KRW",
    "txn_time": 1793603754050,
    "inservice_item_id": "ITEM_1004"
  }
}


모바일 상품

text

{
  "code": 0,
  "message": "결제성공",
  "data": {
    "tid": "1234567890",
    "product_id": "m_1004",
    "quantity": 1,
    "product_price": 1004,
    "product_currency": "KRW",
    "txn_time": 1793603965213,
    "inservice_item_id": null
  }
}

온라인 장바구니 상품

text
{
    "code": 0,
    "message": "OK",
    "data": {
        "tid": "1234567890",
        "products": [
            {
                "tid": "1234567891",
                "product_id": "1004",
                "quantity": 1,
                "product_price": 1004,
                "product_currency": "KRW",
                "txn_time": 1788936011653,
                "inservice_item_id": "ITEM_1004"
            },
            {
                "tid": "1234567892",
                "product_id": "1005",
                "quantity": 1,
                "product_price": 1005,
                "product_currency": "KRW",
                "txn_time": 1788936011653,
                "inservice_item_id": "ITEM_1005"
            }
        ]
    }
}
결제 유효성 체크(BULK)
  • 결제 유효성 체크 (BULK)

Request

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": "1234567890",
            "bill_platform_type": "MOBILE", 
            "noti_type": "IAP_PURCHASE ",
            "guid": "123456",
            "member_no": 123456
        },{
            "tid": "1234567889",
            "bill_platform_type": "SHOP",
            "noti_type": "ONLINE_PURCHASE",
            "guid": "123456",
            "member_no": 123456
        }
    ]
}

Parameter (Path)

NameTypeRequiredDefault ValueExampleDescription
service_idStringY-STOVE_XPFWMS서비스 아이디

Request Body

NameTypeRequiredDefault ValueExampleDescription
detailsArrayListY--상세
- 최대 100 개
details[].tidStringY-1234567890스토브 빌링에서 발급한 주문번호
details[].bill_platform_typeStringY-MOBILE결제 유효성 체크 플랫폼 타입
- MOBILE
-SHOP
details[].noti_typeStringY-IAP_PURCHASE구분
- ONLINE_PURCHASE : 온라인일반상품 구매
-ONLINE_CART_PURCHASE: 온라인장바구니상품 구매
-IAP_PURCHASE: 모바일 일반상품 구매
-IAP_SUBSCRIPT : 모바일 구독상품 구매
-IAP_OOAP
-IAP_PURCHASE: 모바일 OOAP 상품 구매
details[].guidStringN--스토브 회원 GUID
- guid가 없는 게임을 제외하고는 필수
details[].member_noNumberN--회원 번호
- guid 가 없는 게임의 경우에만 필수

Response

NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0응답 코드
messageStringY-OK응답 메시지
dataObjectN--응답 값

data (온라인 상품, 모바일 상품)

NameTypeRequiredDefault ValueExampleDescription
tidStringY-1234567890스토브 빌링에서 발급한 상품 주문번호
product_idStringY-p1004스토브 플랫폼에 등록한 상품 코드
quantityNumberN120온라인 상품 (SHOP) 응답 값
product_priceStringY-1100, 0.99거래 금액
product_currencyStringY-KRW, USD해당 금액의 통화
txn_timeNumberY-1644489139000결제 시각(Unix Timestamp, UTC+0 기준)
inservice_item_idStringY-cp1004게임내 아이템ID
guidStringN-123456모바일 상품 ( MOBILE) 응답 값

text

{
    "code": 0,
    "message": "OK",
    "data": [
        {
            "tid": "1234567890",
            "product_id": "1004",
            "product_price": 1004,
            "product_currency": "KRW",
            "txn_time": 1785315028733,
            "inservice_item_id": "1004",
            "quantity": 1
        },
        {
            "tid": 1234567889,
            "product_id": "1005",
            "product_price": 1005,
            "product_currency": "KRW",
            "txn_time": 1769036487000,
            "inservice_item_id": null,
            "guid": "123456"
        }
    ]
}
비정상 환불
  • 비정상 환불 목록 수신
  • 모바일(Google Play, Apple App Store)

Request

text
curl --location --request GET 'https://api.onstove.com/bill-cpm/v1.0/{service_id}/voidedlist?guid={guid}&member_no={member_no}&character_no={character_no}' \
--header 'Authorization: Bearer {server_token}' \
--header 'X-Lang: ko' \
--header 'caller-id: {caller-id}'

Parameter (Path)

NameTypeRequiredDefault ValueExampleDescription
service_idStringY-STOVE_XPFWMS서비스 아이디

Parameter (Query String)

NameTypeRequiredDefault ValueExampleDescription
bill_platform_typeStringN-MOBILE비정상 환불 내역 플랫폼 타입
- MOBILE
guidStringN-265265게임 유저 유일키
- member_no / guid 중 하나는 필수
member_noLongN-123456회원 번호
- member_no / guid 중 하나는 필수
- guid가 없는 게임은 member_no 사용
character_noLongN-624462캐릭터 번호
market_codeStringN-GOOGLE_PLAY마켓 코드
GOOGLE_PLAY, APPLE_APP_STORE

Response

NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0응답 코드
messageStringY-OK응답 메시지
dataObjectN--응답 값

data

NameTypeRequiredDefault ValueExampleDescription
total_countIntY-2조회 조건에 해당하는 총 환불 건수 (list 건수와 동일)
listArrayY-환불 내역 목록. 환불 내역이 없는 경우 빈 배열()로 반환됩니다.

list

NameTypeRequiredDefault ValueExampleDescription
tidLongY-1234567스토브 빌링에서 발급한 주문번호
market_codeStringY-GOOGLE_PLAY마켓 코드
MOBILE: GOOGLE_PLAY, APPLE_APP_STORE
product_idStringY-123456스토브 플랫폼에 등록한 상품 코드
market_product_idStringY-123456마켓에 등록된 상품의 코드
market_user_idStringN-123456마켓 회원 아이디 (현재 STEAM만 제공 = steam_id, 모바일 마켓 미제공 → null)
inservice_item_idStringN-cp7892게임 내 아이템 ID
user_idStringY-265265GUID 게임 시 스토브 GUID, 아닐 경우 member_no
character_noLongY-123456게임 캐릭터 별로 발급되는 유일키 (STOVE에서 발급)
purchase_dtLongY-1699845522000결제 일자 (UTC Timestamp, ms)
voided_dtLongY-1699845522000환불 일자 (UTC Timestamp, ms)
text
{
    "code": 0,
    "message": "OK",     
    "data": {
        "total_count": 2,
        "list": [
            {
                "tid": 1234567,
                "market_code": "GOOGLE_PLAY",
                "product_id": "mycard_002",
                "market_product_id": "mycard_002",
                "market_user_id": null,
                "inservice_item_id": null,
                "user_id": "265265",
                "character_no": 265265,
                "purchase_dt": 1769495288000,
                "voided_dt": 1769496574000
            },
            {
                "tid": 1234568,
                "market_code": "GOOGLE_PLAY",
                "product_id": "mycard_005",
                "market_product_id": "mycard_005",
                "market_user_id": null,
                "inservice_item_id": null,
                "user_id": "265265",
                "character_no": 265265,
                "purchase_dt": 1769492694000,
                "voided_dt": 1769493573000
            }
        ]
    },
}



아이템 회수 알림
  • 모바일 (App Store / Google Play)
    • Request
NameTypeRequiredDefault ValueExampleDescription
tidLongY-1609997628158350014STOVE에서 결제 완료 시 전달한 주문번호
guidStringY-200000006062게임 유저 유일키
market_codeStringY-GOOGLE_PLAY, APPLE_APP_STORE환불가능여부를 요청한 마켓코드 (GOOGLE_PLAY: 구글, APPLE_APP_STORE: 애플)
product_idStringY-l_0001스토브 아이템 아이디
text
{
  "tid" : 1609997628158350014,
  "guid": "200000006062",
  "market_code": "GOOGLE_PLAY",
  "product_id": "l_0001"
}

NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0응답 코드
messageStringY-성공응답 메시지
dataJObjectY--회수 판정 결과가 담긴 객체

data

NameTypeRequiredDefault ValueExampleDescription
decisionIntegerY-0환불승인여부 (0: APPROVE, 1: REJECT)
item_statusIntegerY-00: 회수가능(아이템 회수), 1: 회수불가
text
{
  "code" : 0,
  "message":"성공",
  "data": {
    "decision":0,
    "item_status":0
  }
}

  • 인게임 상점(PC), 스팀 상점
    • Request
NameTypeRequiredDefault ValueExampleDescription
tidLongY-1609997628158350014STOVE에서 결제 완료 시 전달한 주문번호
guidStringY-200000006062게임 유저 유일키
market_codeStringY-ONLINE환불가능여부를 요청한 마켓코드 (ONLINE: PC 온라인/스팀)
inservice_item_idStringY-l_0001게임사 아이템 아이디
text
{
  "tid": 1609997628158350014,
  "guid": "200000006062",
  "market_code": "ONLINE",
  "inservice_item_id": "l_0001"
}

NameTypeRequiredDefault ValueExampleDescription
codeIntegerY-0응답 코드
messageStringY-성공응답 메시지
dataJObjectY--회수 판정 결과가 담긴 객체

data

NameTypeRequiredDefault ValueExampleDescription
decisionIntegerY-0환불승인여부 (0: APPROVE, 1: REJECT)
item_statusIntegerY-00: 회수가능(아이템 회수), 1: 회수불가
text
{
  "code" : 0,
  "message":"성공",
  "data": {
    "decision":0,
    "item_status":0
  }
}

NameTypeRequiredDefault ValueExampleDescription
tidLongY-1609997628158350014STOVE에서 결제 완료 시 전달한 주문번호
guidStringY-200000006062게임 유저 유일키
market_codeStringY-ONLINE_CART환불가능여부를 요청한 마켓코드 (ONLINE_CART: 웹 상점 장바구니/묶음 결제)
itemsArrayY--회수 대상 구매 상품 목록 (BULK 처리)

items

NameTypeRequiredDefault ValueExampleDescription
tidLongY-1234567개별 구매 상품의 주문번호 (구매 상세 TID)
inservice_item_idStringY-l_0001게임사 아이템 아이디
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-0응답 코드
messageStringY-성공응답 메시지
dataJObjectY--회수 판정 결과가 담긴 객체

data

NameTypeRequiredDefault ValueExampleDescription
decisionIntegerY-0환불승인여부 (0: APPROVE, 1: REJECT)
itemsArrayY--상품별 회수 판정 결과 목록 (BULK 처리)

items

NameTypeRequiredDefault ValueExampleDescription
tidLongY-1234567개별 구매 상품의 주문번호
item_statusIntegerY-00: 회수가능(아이템 회수), 1: 회수불가
text
{
  "code": 0,
  "message": "성공",
  "data": {
    "decision": 0,
    "items": [
      { "tid": 1234567, "item_status": 0 },
      { "tid": 1234568, "item_status": 0 }
    ]
  }
}

자주 묻는 질문



Q1. 파트너스에 빌링 정보를 등록하지 않으면 어떻게 되나요?
A. 파트너스에 마켓 별 IAP 정보(마켓 검증 키, OAuth Client ID/Secret, Refresh Token 등)가 입력되지 않으면 결제 완료 후
상품 지급 요청이 정상 동작하지 않아요. 연동 시작 전 반드시 모든 항목을 등록해 주세요.
Q2. 결제 완료 알림을 받지 못했거나 처리에 실패한 경우 어떻게 하나요?
A. 모바일 빌링의 경우 1~5분 간격으로 최대 100회까지 재 전송을 시도해요.
100회 이후에도 실패한 경우에는 [파트너스] > [MobileBilling] > [판매 내역 조회 및 운영] > [마켓 판매 내역]에서 수동으로 지급 처리해야 해요.
Q3. TID는 어떻게 관리해야 하나요?
A. TID(스토브 빌링 결제 주문번호)는 게임 서버에 저장하여 관리해야 해요.
동일한 결제 알림이 재 전송될 수 있으므로, TID를 기준으로 중복 지급 여부를 확인하는 로직이 반드시 필요해요.
Q4. 비정상 환불 재결제 처리 시 voided_tid 필드는 어떻게 처리해야 하나요?
A. voided_tid 필드에 데이터가 있으면 해당 요청이 비정상 환불 후 재결제에 해당하는 것이에요.
이 경우 게임 서버에서는 아이템을 지급하지 않도록 처리해야 해요. 재결제 처리 목적으로만 사용하는 결제이기 때문이에요.
Q5. 비정상 환불 팝업(STOVE 공통 UI)을 사용할 때 판매 종료된 상품은 어떻게 관리해야 하나요?
A. 재결제 팝업은 동일한 환불 상품 ID로 재결제가 이루어지는 구조이에요.
모바일 환경에서 판매 종료된 상품이더라도 스토브 파트너스와 마켓 내 상품이 반드시 판매 상태로 유지되어야 해요.
Disabled 상태로 변경하면 안 돼요.
Q6. 구독 상품의 갱신 알림은 어떻게 받나요?
A. 구독 갱신 알림 수신을 위해 마켓별 사전 설정이 필요해요.
iOS는 App Store Connect에서 서버 알림 URL을 버전 2 알림으로 변경 등록해야 하고,
Android는 Google Cloud Pub/Sub 주제(Topic)와 구독(Subscription)을 생성하여 스토브 빌링 서버 URL을 엔드포인트로 등록해야 해요.
Q7. Google IAP 연동을 위한 Refresh Token은 어떻게 발급하나요?
A. Google Developers OAuth 2.0 Playground에서 발급할 수 있어요.
OAuth 2.0 Configuration에서 "Use your own OAuth credentials"를 체크한 후 OAuth Client ID와 Client Secret을 입력하고,
Play Android Developer API 범위를 선택해 Authorize API를 클릭해요.
Step 2에서 "Exchange authorization code for tokens" 버튼을 클릭하면 Refresh Token을 얻을 수 있어요.
발급된 정보는 스토브 파트너스 > 빌링 설정 정보에 입력해요.
Q8. iOS 2025년 1월 이후 비승인 환불 수신 방식 변경 사항이 있나요?
A. 네, 2025년 1월 24일부터 iOS 영수증 서명 인증서 변경으로 인해 앱 웹 주소 호출 방식이 중단되고 App Store Server API 호출 방식으로 변경됐어요.
App Store Connect에서 서버 알림 URL을 버전 1에서 버전 2 알림으로 반드시 변경해야 해요.
Q9. PC SDK 빌링 연동 시 WebView 모드에 따라 주의할 사항이 있나요?
A. 게임 화면이 Exclusive Fullscreen(FSE) 모드일 때 구매창 WebView 모드에 따라 표시 여부가 달라져요.
WebViewMode::INTERNAL은 게임 화면 위에 창을 겹쳐 그리는 방식이라, Exclusive Fullscreen 모드에서는 구매창이 그려지지 않아요.
WebViewMode::EXTERNAL은 화면 전체를 덮는 별도 창으로 그리는 방식이라 Exclusive Fullscreen 모드에서도 구매창은 표시되지만, 별도 창이 앞으로 나오면서 게임 화면이 최소화(minimize)되는 문제가 있어요.
따라서 Exclusive Fullscreen을 쓰는 게임은 구매창을 띄울 때 게임 화면을 Borderless Windowed Fullscreen으로 전환하는 방법을 권장해요.



문의가 필요하신가요?