- 마지막 업데이트
결제
이해하기
결제 지원 개요
스토브는 PC 온라인 결제와 모바일 마켓 결제, 두 가지 결제 종류를 지원해요.
결제 종류에 따라 지원 통화·결제 수단·한도·취소 방식이 달라요.
| 결제 종류 | 설명 |
|---|---|
| PC 온라인 결제 | PC 버전 게임의 웹상점·인게임 상점 결제 (스토브 제공 결제창 이용). |
| 모바일 마켓 결제 | 구글·애플 등 앱 마켓 출시 게임의 결제 (마켓 제공 IAP(인앱 결제) 결제창 이용). |
결제 계정 본인 확인
ㆍ 최소한의 본인 확인이 된 계정만 결제 가능
ㆍ 한국: 본인 인증 / 글로벌: 이메일 인증
스팀런처로 배포한 게임의 결제
스팀런처로 실행되는 게임의 결제도 PC 온라인 결제에 속하지만, 결제창이 스토브 결제 웹뷰가 아니라 스팀 결제 오버레이로 대체돼요. 자세한 동선은 개발하기 → PC IAP → 스팀 결제 를 참고하세요.
결제 지원 통화
| 분류 | 통화 | 설명 | 이 통화로 결제하는 계정 |
|---|---|---|---|
| PC 온라인 결제 | KRW | 대한민국 원 | 한국 가입 계정 |
| USD | 미국 달러 | 미국 가입 계정, 그리고 지원 통화가 없는 국가의 가입 계정 | |
| JPY | 일본 엔 | 일본 가입 계정 | |
| EUR | 유로 | 유로를 쓰는 지정 국가의 가입 계정 (하단 목록 참조) | |
| THB | 태국 바트 | 태국 가입 계정 | |
| PHP | 필리핀 페소 | 필리핀 가입 계정 | |
| TWD | 대만 달러 | 대만 가입 계정 | |
| 모바일 마켓 결제 | - | 마켓 결제 지원 통화 | 이용자의 각 마켓 계정에 설정된 지원 통화로 결제 |
결제 통화 유의사항
ㆍ 불가리아: 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 설정
- Google Play Console API 액세스 권한 얻기
- Google Cloud 프로젝트 생성 (프로젝트 만들기 / API 추가 / OAuth 동의 화면 설정 및 클라이언트 ID 생성)
- OAuth 2.0 Playground Refresh Token 생성
- 스토브 파트너스 빌링 설정 정보 입력
- 빌링 정보 입력 가이드
- 구글 플레이 빌링 정보 등록 (마켓 검증 키 / 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): 아래 저장소·의존성을 추가하세요. (릴리즈 최신 버전을 확인해서 적용하세요.)groovyrepositories { 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를 검색해 추가하고 활성 상태인지 확인하세요.
- Android (
- 파트너스 빌링 정보 등록: 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를 반드시 호출해야 해요. (코드는 아래 샘플 코드의 필수 멀티캐릭터(다중 재화) 관리 설정 단락 참고)
개발 흐름
- 초기화: 로그인 완료 이후
IAP.initialize를 호출하세요. 실패 시Auth.UnauthorizedError(30002)는 로그인 흐름으로 유도하고,IAPError.InitializeError(40003)면userInfo의responseCode(BillingClient.BillingResponseCode)와debugMessage로 마켓 환경 점검을 안내하세요. - 결제 리스너 등록: 초기화 성공 콜백 안에서
IAP.setListener로 결제 결과 콜백을 등록하세요. 정상 구매·취소·계정 불일치·검증 대기·지급 대기·마켓 오류가 모두 이 리스너로 전달돼요. - 상점 구성:
IAP.fetchProducts로 상품 목록을 조회하고, 응답IAPProduct의ProductState(Available/Waiting/Purchased) 값에 따라 구매 버튼 활성/비활성을 분기 처리하세요. - 구매 진행:
Available상품에 한해IAP.startPurchase를 호출하세요.Waiting은 진행 중이므로 버튼 비활성화,Purchased는 미지급 상태이므로IAP.flush로 재지급 처리하세요. - flush: 결제됐지만 미지급 상품이 있을 때 또는 앱 재실행 시
IAP.flush를 호출해 컨슘·재지급 요청을 진행하세요. 결과는setListener콜백으로 돌아와요. - (옵션) 부가 기능: 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)를 초기화해요. 초기화가 완료돼야 상품 조회·구매 호출이 가능해요.
- 추천 시점: 로그인 성공 이후

#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
| Domain | ErrorCode | Description |
|---|---|---|
| com.stove.success | 0 | Success |
| com.stove.auth | 30002 | UnauthorizedErrorResult |
| com.stove.iap | 40003 | InitializeError. Android PlayBilling의 경우 userInfo의 'responseCode'와 'debugMessage' 참조 |
| com.stove.iap | 40010 | iOS에 한해서만 pay country code가 nil일 경우 |
| com.stove.server | 20001 | initialize fail on precheck |
| com.stove.server | 20002 | initialize fail on afterCheck |
| com.stove.server | 20003 | initialize fail on send tid |
| com.stove.server | 20004 | initialize fail on send tid : error parsing response |
setListener
IAP 초기화 성공 이후 결제 결과를 받을 리스너를 설정해요. flush의 처리 결과도 이 리스너로 전달돼요.
- 추천 시점: 초기화 완료 직후
product값이 있으면 구매 시도한 상품 상태를 응답받은 상태로 변경해요. 특정 상황에서Available이외의 상태가 올 수 있어요.
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
| Domain | ErrorCode | Description |
|---|---|---|
| com.stove.success | 0 | Success |
| com.stove.cancel | 10 | Canceled |
| com.stove.iap | 40000 | SuccessButUserMissMatch |
| com.stove.iap | 40001 | Waiting |
| com.stove.iap | 40002 | MarketError (Android: BillingResponseCode / iOS: 결제 실패) |
| com.stove.iap | 40006 | Purchased |
| com.stove.server | 10001 | invalid parameters |
| com.stove.server | 10004 | not exists noti-api |
| com.stove.server | 10007 | is not supported environment |
| com.stove.server | 30000 | verify fail |
| com.stove.server | 30006 | canceled transaction - verify fail |
| com.stove.server | 30007 | revoked transaction - verify fail |
| com.stove.server | 30011 | completed transaction |
| com.stove.server | 30012 | duplicate store receipt |
| com.stove.server | 30014 | failed transaction |
| com.stove.server | 30015 | sandbox transaction (LIVE에서 테스트 계정 미등록 시 발생) |
| com.stove.server | 40001 | supply server response is 'fail' |
| com.stove.server | 40005 | noti api call fail |
| com.stove.server | 40006 | cash api call fail |
| com.stove.server | 40007 | itembox api call fail |
상점 구성하기
마켓에서 상품을 조회해 상점을 구성해요. 조회 응답인 IAPProduct의 주요 필드는 다음과 같아요.

IAPProduct 필드
| 필드명 | 설명 | 예시 |
|---|---|---|
| ProductType | 상품 종류 (inapp/subs) | inapp |
| productIdentifier | 마켓 등록 상품ID (구매 요청 시 전달) | google_item01 |
| stoveProductId | 스토브 파트너스에 등록된 상품ID | stove_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로 재지급 처리)
#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 이상)
상점에는 아래 순서로 구매 제한을 표시해요.
- 제한 수량이
0인 기준은 표시하지 않아요. - 기준마다 남은 수량(
제한 수량 - 구매 수량)을 계산해요. - 한 기준이라도 남은 수량이 없으면 구매 버튼을 비활성화해요.
- 결제가 끝나면 상품 목록을 다시 조회해 수치를 갱신해요.
| 기준 | 의미 | 표시 예시 |
|---|---|---|
| 계정 | 이 계정으로 구매할 수 있는 수량 | 계정당 1/5 |
| 캐릭터 | 지금 캐릭터로 구매할 수 있는 수량 | 캐릭터당 0/1 |
| 월드 | 월드의 모든 이용자가 함께 쓰는 한정 수량 | 남은 수량 880 |
- 월드 구매 수량은 모든 이용자의 합계예요. 내 구매 횟수가 아니라 남은 수량으로 보여 주는 것을 권장해요.
| 상태 | 조건 | 버튼 예시 |
|---|---|---|
| 제한 없음 | 제한 수량이 모두 0 | 구매 |
| 구매 가능 | 모든 기준에 남은 수량이 있음 | 구매 + 제한 문구 |
| 구매 한도 도달 | 계정 또는 캐릭터 기준 남은 수량 없음 | 구매 완료 (비활성) |
| 품절 | 월드 기준 남은 수량 없음 | 품절 (비활성) |
- 구매 제한보다 상품 상태(
ProductState)를 먼저 확인해요.Waiting·Purchased상품은 위 권장 사항대로 처리해요. - 상점에 들어올 때 · 캐릭터를 바꿨을 때 · 결제가 끝났을 때 상품 목록을 조회해요. 수치는 조회 시점 기준이에요.
- 화면 표시는 안내용이에요. 조회 이후 다른 기기나 다른 이용자의 구매로 한도가 찰 수 있고, 이때는 결제 단계에서 서버가 구매를 거절해요. 결제 실패를 받으면 상품 목록을 다시 조회해 화면을 갱신해요.
- 구매 제한 정보를 받지 못해 값이 모두
0이면 제한 문구 없이 구매 버튼만 표시돼요.
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
| Domain | ErrorCode | Description |
|---|---|---|
| com.stove.success | 0 | Success |
| com.stove.server | 20000 | not exists value |
| com.stove.server | 21000 | No content |
| com.stove.server | 21001 | not exists game |
| com.stove.server | 21002 | Not exists marketCode |
| com.stove.base.network | 10001 | NoConnectionError |
| com.stove.base.network | 10002 | TimeoutError |
구매하기
상품의 ProductState에 따라 다르게 처리해요. Available인 경우만 startPurchase를 호출하고, Purchased는 flush로 재지급 처리해요.
#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
| Domain | ErrorCode | Description |
|---|---|---|
| com.stove.success | 0 | Success |
| com.stove.auth | 30002 | UnauthorizedError |
| com.stove.iap | 40003 | InitializeError |
| com.stove.iap | 40004 | InvalidProduct |
| com.stove.iap | 40006 | PurchasedNeedFlush |
| com.stove.iap | 40008 | ListenerError |
| com.stove.iap | 40009 | InvalidUser |
| com.stove.iap | 40010 | iOS pay country code nil |
| com.stove.server | 20005 | initialize fail on already purchased split product |
| com.stove.server | 93102 | invalid product info |
| com.stove.server | 93103 | is not sales product |
| com.stove.server | 93104 | limit purchase |
| com.stove.server | 93106 | exists purchased subscript product |
| com.stove.server | 93107 | not subscript product |
| com.stove.server | 93108 | product is subscript and limit |
| com.stove.server | 93110 | over limit on purchase of payment amount |
| com.stove.base.network | 10001 | NoConnectionError |
| com.stove.base.network | 10002 | TimeoutError |
flush
결제는 됐지만 아직 지급 전인 상품의 컨슘 처리 및 상품 재지급 요청 용도예요. 처리 결과는 IAP.setListener에 설정된 리스너로 전달돼요.
public void Flush()
{
IAP.Flush();
// 결과는 setListener의 콜백으로 전달됨
}
결제 시 developer payload 설정
결제 호출 시 serviceOrderId를 설정하면 결제 응답에서 확인할 수 있어요.
⚠️ 주의
payload 값은 이용자의 일부 재지급 케이스(앱 삭제 등)에서 100% 전달이 보장되지 않아요.
지급에 영향을 주는 주요 정보로는 사용하지 않도록 주의하세요.
string serviceOrderId = "set your developer payload";
IAP.StartPurchase(product, serviceOrderId, null, (Result result) => { });
환불 내역 조회 (데이터)
이용자의 마켓 환불 내역을 화면 없이 데이터로만 받아요. 환불 내역이 있는 이용자에게 게임에서 직접 재결제를 안내하거나 접속을 제한할 때 써요. SDK 가 제공하는 화면으로 처리하려면 아래 환불 내역 조회 UI(handleVoidedPurchases)를 쓰세요.
IAP.FetchVoidedPurchases((Result result, List<Dictionary<string, object>> voidedPurchases) =>
{
if (result.IsSuccessful)
{
if (voidedPurchases.Count > 0)
{
// 환불 내역이 있으면 재결제 안내 또는 접속 제한 등 게임 정책에 따라 처리
}
else
{
// 환불 내역 없음 → 게임 진입
}
}
else
{
// 조회 실패
OperationUI.HandleResult(result, (Result operationResult) => { });
}
});
환불 내역 조회 UI
이용자의 마켓 환불 내역을 화면에 노출해요. 환불 결제가 필요한 경우 이 화면에서 처리할 수 있어요.
#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} 조합 형태로 가이드가 변경됐어요. 본 설정은 모바일 환경에서만 적용돼요.
IAP.SetCustomBillingGUID("{STOVE_guid}_{STOVE_character_no}");
iOS Promoted
App Store 내 프로모션 상품 결제 연동이에요.
- iOS 11 이상부터 사용 가능
purchasePromotion호출 시점은 초기화·로그인 완료 이후
코드 예시 (iOS)
#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를 직접 연동·초기화해야 해요. 자세한 동선은 아래 스팀 결제 를 참고하세요.
개발 흐름
- 초기화:
Base_Initialize완료 후IAP_Initialize(shopKey)(부모 창이 필요하면IAP_InitializeWithWndInfo)로 IAP 모듈을 초기화해요. - 약관 동의 확인:
IAP_FetchTermsAgreement로 필수 약관 동의 여부를 조회하고, 미동의 시 약관 동의 흐름을 진행해요. - 상점 구성: 카테고리 조회(
IAP_FetchShopCategories)와 상품 목록 조회(IAP_FetchProducts)로 상품 목록을 가져와 UI를 구성해요. - 구매 진행: 이용자 선택 시
IAP_StartPurchase/IAP_StartPurchaseEx를 호출해요.StovePCPurchaseOption의 operation으로 결제 UI와 확정 방식을, webViewMode로 결제창 표시 방식을 정해요. (아래 구매 옵션과 결제창 표시 방식 참고) 조회한 상품 정보를 구매 파라미터에 옮겨 담는 방법은 아래 상품 조회 결과를 구매 파라미터로 옮기기 를 참고하세요. - 구매 확정/검증: 결제 완료 후
IAP_ConfirmPurchase로 클라이언트 측 확정을 호출하고, 게임 서버에서는 결제 유효성 체크 API로 2차 검증을 수행해요. - 보관함: 필요 시 인벤토리 조회(
IAP_FetchInventory)를 활용해요. - 부가 동작: 게임해지(약관철회) UI는
IAP_WithdrawGame, 열린 결제 창 일괄 닫기는IAP_CloseAllPopups를 사용해요. - 정리: 게임 종료 직전에
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_WEBVIEW | SDK 웹뷰 | 게임이 직접 호출 | 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가 더 간단해요.
- 주문 생성:
IAP_StartPurchase(Ex)를 호출하면 onFinished로 거래 번호(transactionMasterNumber)와 1회용 결제 URL(oneTimePaymentUrl)이 와요. 이 시점은 결제 전이에요. 거래 번호는 비정상 종료에 대비해 로컬에 저장하고, 재시작 시 저장된 번호가 있으면IAP_ConfirmPurchase로 마무리하세요. - 0원 결제 확인:
purchaseProgress가NOT_NEED_PAYMENT_WINDOW이면 결제 URL이 없고 이미 구매가 끝난 상태예요. 창을 열지 말고 바로IAP_ConfirmPurchase를 호출해 지급 목록을 받으세요. - 결제창 표시: 받은 URL을 원하는 브라우저 컴포넌트로 열어요. SDK가 결제 페이지와 따로 통신하지 않으므로 브라우저에 연동 코드를 넣을 필요가 없어요. 결제 페이지는 결제 수단에 따라 새 창을 열 수 있으니 새 창 열기를 허용해 두세요. URL은 1회용이라 다시 시도하려면
IAP_StartPurchase를 다시 호출해요. - 구매 확인: 결제창이 닫히면 보관해 둔 거래 번호로
IAP_ConfirmPurchase를 무조건 한 번 호출하세요. 조회 API라 결제를 안 했든 취소했든 호출해도 부작용이 없어요. 첫 조회가 미확정이면 5초 뒤 한 번만 다시 조회하고, 그래도 미확정이면 "결제 확인" 버튼으로 사용자가 다시 확인하게 하세요. 사용자가 창을 닫지 않고 게임으로 돌아올 수 있으니 이 버튼은 결제 중에 항상 노출하세요. 앞선 콜백이 오기 전에 같은 API를 다시 호출하면 콜백이 덮어써지므로 겹쳐 호출하지 마세요. - 아이템 지급: 아래 세 갈래 판정에서 결제 완료로 확인된 경우에만 지급해요.
ConfirmPurchase 결과는 세 갈래로 읽어요
| 콜백 결과 | 뜻 | 게임이 할 일 |
|---|---|---|
IsSuccessful() == true 이고 status == true | 결제 완료 | purchasedProducts를 기준으로 아이템을 지급해요. |
IsSuccessful() == true 이고 status == false | 결제 미완료(취소, 아직 결제 안 함, 서버 반영 전) | 지급하지 않아요. 결제창을 닫은 직후라면 5초 뒤 한 번만 다시 조회해요. |
IsSuccessful() == false | 조회 실패(네트워크, 서버 오류, 잘못된 거래 번호) | 지급하지 않아요. 재시도하거나 사용자에게 안내해요. 미승인 주문은 external_error 22001로 올 수 있으며, 이 경우도 미완료로 다뤄요. |
스토브런처와 스팀런처를 한 가지 조건으로 판정하려면
위 표는 스토브런처 동선 기준이에요. 스팀런처 동선에서는 SDK가 status를 항상 false로 내려주므로, IsSuccessful과 status를 함께 보는 조건을 그대로 쓰면 스팀에서 확정된 결제가 실패로 처리돼요. 콜백 값만으로는 두 동선을 구분할 수 없고 조회 API도 없으니, 외부플랫폼연동모듈로 스토브 인증을 마친 시점에 플래그를 세워 두고 아래처럼 한 함수에서 판정하세요. SDK는 그 초기화 때 넘긴 스팀 유저 아이디(SteamUserId)가 있으면 스팀 결제 동선으로, 없으면 스토브 결제창 동선으로 자동 처리해요.
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 (구매 요청) | 가져올 값 | 설명 |
|---|---|---|
SetProductId | StovePCProduct::GetProductId() | 플랫폼 상품 아이디예요. 그대로 옮겨요. |
SetSalePrice | StovePCProduct::GetSalePrice() | 결제용 판매가예요. 서버가 이 값을 실제 판매가와 비교하므로 그대로 옮겨요. 정가(GetPrice())나 전시용 가격(GetDisplaySalePrice() 등)을 넣으면 가격 불일치로 구매가 거부될 수 있어요. |
SetQuantity | 이용자가 고른 구매 수량 | StovePCProduct::GetQuantity()는 이 상품을 1회 구매할 때 지급되는 아이템 수량이라 구매 수량이 아니에요. 복사하지 말고 이용자가 고른 수량(보통 1)을 넣어요. |
구매 버튼을 누르는 시점은 조회 콜백보다 늦으므로, 콜백 인자로 받은 배열을 콜백 밖에서 쓰지 말고 상품 아이디와 판매가를 콜백 안에서 게임의 상점 모델에 복사해 두었다가 구매할 때 StovePCOrderProduct를 만들어요. 판매가는 할인 기간 등으로 바뀔 수 있으니 구매 직전에 화면에 보여 준 조회 결과의 값을 써야 해요. IAP_FetchProductsEx로 받는 StovePCProductEx도 같은 getter를 제공하므로 같은 방법으로 옮겨요. 예제의 Game::/Game. 호출과 ShopItem은 개발사가 구현하는 의사(Pseudo) 코드예요.
// 상점 모델 — 조회 콜백에서 복사해 두는 값
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 결과는 위 스토브런처와 스팀런처를 한 가지 조건으로 판정하려면 의 공통 판정으로 읽으세요.
동선
- 상점 구성:
IAP_FetchShopCategories로 카테고리를,IAP_FetchProducts로 상품 목록을 조회해 상점 UI를 구성해요. 여기까지는 기본 동선과 같아요. - 구매 시작: 이용자가 상품을 고르면
IAP_StartPurchase를 호출해요. 상품 정보(productId·salePrice·quantity)만 채우고,StovePCPurchaseOption은 기본값 그대로 두세요. - 두 가지가 동시에 일어나요: ①
IAP_StartPurchase콜백으로 거래 마스터 번호(transactionMasterNumber) 가 도착하고, ② 스팀런처가 게임 위에 스팀 결제 오버레이를 띄워요. 두 동작의 순서는 보장되지 않으니, 콜백에서 받은 거래 마스터 번호를 변수에 보관해 두세요. - 이용자 결제: 이용자가 오버레이에서 구매를 승인하거나 취소해요. 이 화면은 스팀이 그리므로 개발사가 만들 UI는 없어요.
- 결과 수신: 승인·취소 결과는 SDK가 아니라 Steamworks의
MicroTxnAuthorizationResponse_t콜백으로 도착해요. 콜백 등록과 처리는 게임이 연동한 Steamworks SDK 영역이에요. - 구매 확정: 승인된 경우 보관해 둔 거래 마스터 번호로
IAP_ConfirmPurchase를 호출해요. 스팀 동선에는 자동 확정이 없어서 이 호출을 건너뛰면 아이템이 지급되지 않아요. 취소·미승인으로 끝난 주문은 호출하지 않아도 백엔드가 결제 취소로 정리하지만, 결과 콜백을 받지 못한 경우에는 이 호출로 최종 상태를 확인하세요. - 지급 확인:
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가externalError21107로 실패하면 완료되지 않은 이전 스팀 거래가 남아 있는 거예요. 재시도하지 말고 "이전 결제가 진행 중입니다. 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로 정리해요.
#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 웹뷰)을 노출해요.
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를 빈 값으로 전달하면 전체 범위에서 조회돼요.
// 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를 직접 호출하면 중복 확정이 되니 호출하지 마세요.
#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(¶ms,
// 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는 호출되지 않으니 빈 핸들러를 넘겨요. 외부 브라우저로 열 때의 차이는 위 외부 브라우저로 열 때 를 참고하세요.
StovePCPurchaseOption option;
option.SetOperation(StovePCPurchaseOperation::DEFAULT);
params.SetPurchaseOption(option);
IAP_StartPurchaseEx(¶ms,
// 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로 확정해요.
StovePCPurchaseOption option;
option.SetOperation(StovePCPurchaseOperation::WITH_WEBVIEW);
option.SetWebviewMode(Base::WebViewMode::INTERNAL);
option.SetWebviewRect(0, 0, 420, 700);
params.SetPurchaseOption(option);
IAP_StartPurchaseEx(¶ms,
// 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 영역이라 연결 지점만 표시했어요.
#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(¶ms,
[](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차 검증을 수행해야 해요.
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를 구성해요.
IAP_FetchInventory(
[](CallbackResult callbackResult, StovePCInventoryItem* inventoryItems, uint32_t inventoryItemSize)
{
if (callbackResult.GetResult().IsSuccessful())
{
// inventoryItems[0..inventoryItemSize) 로 보관함 UI 구성
}
});
게임 탈퇴와 팝업 정리
게임 탈퇴(약관 철회) UI는 IAP_WithdrawGame으로 표시해요. 열린 IAP 결제 창을 즉시 모두 닫아야 할 때는 IAP_CloseAllPopups를 호출해요.
// 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 연동으로 결제 완료 유효성 체크가 필요해요.
개발 흐름
- SDK 연동으로 전달 받은 아이템 목록에서 결제 요청을 진행해요.
- 결제 요청 후 결제를 진행하면 SDK를 통해서 빌링 서버로 결제정보가 전달돼요.
- 빌링 서버에서는 결제 정보의 유효성을 판단한 후 결제 완료 알림 URL에 등록된 게임서버로 결제 완료 정보를 전달해요.
- 게임서버에서는 결제 정보 유효성 API를 확인한 후 아이템 지급 후 빌링 서버에 응답을 해줘요.
ACL 설정
- STOVE 서비스는 별도 Outbound 제한 정책은 없습니다.
- 만약 '게임서버장비’에서 Inbound ACL 정책 제어가 필요한 경우라면, 기능 테스트 등을 통한 게임내 연결 검증을 필히 권장 드립니다.
빌링 (미들웨어) ACL 설정
| 환경 | NAT IP |
|---|---|
| SandBox | 52.193.143.11 52.196.37.103 52.197.65.49 54.248.156.218 |
| Live | 52.69.38.53 52.192.82.246 13.113.43.215 3.113.195.187 52.197.237.44 |
빌링 (STMo) , ItemBox ACL 설정
| 환경 | NAT IP |
|---|---|
| SandBox | 52.198.86.83 18.176.44.28 18.180.119.9 |
| Live | 52.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_REQUEST | pendingRefundReviewNotification |
| 스토브 빌링의 응답 API | Send Consumption Information | orders.reviewrefund |
| 스토브 빌링의 응답 제한시간 | 12시간 | 48시간 |
응답 제한시간은 스토브 빌링 기준이에요
애플 12시간·구글 48시간은 스토브 빌링이 마켓에 소비 정보를 회신해야 하는 기한으로, 게임 서버가 별도로 대응할 부분은 없어요. 게임 서버는 아래 아이템 회수 요청 API만 정상 응답하면 돼요.
처리 흐름
아이템 회수 요청 API 응답 규격
게임 서버 구현 API
게임 서버는 아래 API를 구현해야 해요. (파트너스 > 빌링 설정에 등록하는 "아이템 회수 알림 URL"이 여기에 대응돼요.)
| 필드 | 값 | 설명 |
|---|---|---|
item_status | int | 아이템 회수 결과: 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
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| service_id | String | Y | - | STOVE_XPFWMS | 게임 코드 |
| bill_platform_type | String | Y | - | SHOP | 결제 유효성 체크 플랫폼 타입
|
| noti_type | String | Y | - | ONLINE_PURCHASE | notification 구분
|
| world_id | String | Y | - | world_1 | 월드(서버) 구분 |
| guid | String | N | - | "1234567890" | 스토브 회원 GUID |
| member_no | Number | N | - | 1234567891 | 회원 번호 |
| character_no | Number | N | - | 1234567892 | 게임 캐릭터 번호 |
| country_cd | String | N | - | "KR" | 가입 국가 |
| age | String | N | - | "10" | 회원 나이 |
| txn_time | String | Y | - | "1793663058725" | 결제 시각(Unix Timestamp, UTC+0 기준) |
| extra_data | String | N | - | - | 요청 추가 데이터(json string) |
| billstore_sync_flag | boolean | N | false | Y | 상점 동기화 여부 - 게임 사 전달 되는 Body에서 제외 |
Data ( 온라인 일반 상품 (PC 인게임), 스팀)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | String | Y | - | - | 스토브 빌링에서 발급한 주문번호 |
| product_id | String | Y | - | - | 스토브 플랫폼에 등록한 상품 코드 |
| quantity | Number | N | - | - | 개별 구매 상품 수량 - 스토브게임 : Required: Y - 스토어 게임 : 2개 이상 구매 시 Required: Y |
| product_currency | String | Y | - | KRW, USD | 해당 금액의 통화 |
| product_price | Number | Y | - | 1100, 0.99 | 스토브 플랫폼에 등록한 상품 금액 |
| inservice_item_id | String | Y | - | - | 게임내 아이템ID |
| service_order_id | String | N | - | - | 서비스 주문 번호 |
| stove_charge_infos | List | Y | - | - | 충전 창 재화 사용 내역 |
| stove_charge_infos[].charge_deduct_val | Number | N | - | - | 충전 가격 |
| stove_charge_infos[].charge_display_deduct_val | Number | N | - | - | 충전 노출 가격 |
| stove_charge_infos[].charge_type | Number | N | - | - | 결제 수단 코드 |
| stove_charge_infos[].charge_type_name | String | N | - | - | 결제 수단 명 |
{
"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 ( 온라인장바구니상품)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | String | Y | - | - | 스토브 빌링에서 발급한 주문번호 |
| stove_charge_infos | List | Y | - | - | 충전 창 재화 사용 내역 |
| stove_charge_infos[].charge_deduct_val | Number | N | - | - | 충전 가격 |
| stove_charge_infos[].charge_display_deduct_val | Number | N | - | - | 충전 노출 가격 |
| stove_charge_infos[].charge_type | Number | N | - | - | 결제 수단 코드 |
| stove_charge_infos[].charge_type_name | String | N | - | - | 결제 수단 명 |
| products | List | Y | - | - | 상품정보 |
| products[].tid | String | Y | - | 1234567880 | 스토브 빌링에서 발급한 상품 주문번호 |
| products[].product_id | String | Y | - | - | 스토브 플랫폼에 등록한 상품 코드 |
| products[].quantity | Number | N | - | - | 개별 구매 상품 수량 - 스토브게임 : Required: Y - 스토어 게임 : 2개 이상 구매 시 Required: Y |
| products[].product_currency | String | Y | - | KRW, USD | 해당 금액의 통화 |
| products[].product_price | Number | Y | - | 1100, 0.99 | 스토브 플랫폼에 등록한 상품 금액 |
| products[].inservice_item_id | String | Y | - | - | 게임내 아이템ID |
| products[].service_order_id | String | N | - | - | 서비스 주문 번호 |
{
"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 ( 모바일 일반상품 / OOAP 상품)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | String | Y | - | - | 스토브 빌링에서 발급한 주문번호 |
| pay_type | String | Y | - | - | 결제 구분 - 일반 : INAPP - OOAP_PROMO : 프로모션 코드 결제 - OOAP_POINT : 포인트 결제 |
| market_code | String | Y | - | APPLE_APP_STORE, GOOGLE_PLAY, HUAWEI_APP_GALLERY, ONE_STORE | 마켓 코드 |
| market_product_id | String | Y | - | - | 마켓에 등록된 상품의 코드 |
| product_id | String | Y | - | - | 스토브 플랫폼에 등록한 상품 코드 |
| product_currency | String | Y | - | KRW, USD | 해당 금액의 통화 |
| product_price | String | Y | - | KRW, USD | 해당 금액의 통화 |
| price_on_market | String | Y | - | KRW, USD | 해당 금액의 통화 |
| currency_on_market | String | Y | - | KRW, USD | 해당 금액의 통화 |
| product_price_tier | String | Y | - | 1 | 해당 상품에 설정된 tier번호 |
| inservice_item_id | String | N | - | - | 게임 내 아이템ID |
| service_order_id | String | N | - | - | 결제요청시 결제(IAP) 서버에 전달한 게임 payload(현재 미지원 Spec) |
| voided_tid | String | N | - | - | 환불 TID |
| supply_items | Array | N | - | - | 상품구매시 지급해야할 아이템 정보(재화 정보 제외) |
| supply_items[].service_item_code | String | Y | - | - | 아이템 코드번호 |
| supply_items[].total_amount | String | Y | - | - | 지급 수량 - 최소 1이상 |
| supply_items[].item_desc | String | N | - | - | 아이템 부가정보/설명 |
{
"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
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| code | Integer | Y | - | 0 | 응답 코드 |
| message | String | Y | - | 성공 | 응답 메시지 |
| data | Object | N | {} | {} | 응답 데이터 |
{
"code": 0,
"message": "OK",
"data": {}
}
결제 유효성 체크
- 결제 유효성 체크
Request
curl --location --request GET 'https://api.onstove.com/bill-cpm/v1.0/payment/{service_id}/detail?bill_platform_type={bill_platform_type}&guid={guid}¬i_type={noti_type}&tid={tid}' \
--header 'Authorization: Bearer {server_token}' \
--header 'caller-id: {caller-id}'
Parameter (Path)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| service_id | String | Y | - | STOVE_XPFWMS | 서비스 아이디 |
Parameter (Query String)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| bill_platform_type | String | Y | - | MOBILE | 결제 유효성 체크 플랫폼 타입 - MOBILE - SHOP |
| noti_type | String | Y | - | IAP_PURCHASE | 구분 - ONLINE_PURCHASE : 온라인일반상품 구매 - ONLINE_CART_PURCHASE: 온라인장바구니상품 구매 - IAP_PURCHASE: 모바일 일반상품 구매- IAP_SUBSCRIPT : 모바일 구독상품 구매- IAP_OOAP- IAP_PURCHASE: 모바일 OOAP 상품 구매 |
| guid | String | N | - | - | 스토브 회원 GUID - guid가 없는 게임을 제외하고는 필수 |
| member_no | Number | N | - | - | 회원 번호 - guid 가 없는 게임의 경우에만 필수 |
Response
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| code | Integer | Y | - | 0 | 응답 코드 |
| message | String | Y | - | OK | 응답 메시지 |
| data | Object | N | - | - | 응답 값 |
data (온라인 상품, 모바일 상품)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | String | Y | - | 1234567890 | 스토브 빌링에서 발급한 상품 주문번호 |
| product_id | String | Y | - | p1004 | 스토브 플랫폼에 등록한 상품 코드 |
| quantity | Number | N | 1 | 20 | 개별 상품 수량 |
| product_price | String | Y | - | 1100, 0.99 | 거래 금액 |
| product_currency | String | Y | - | KRW, USD | 해당 금액의 통화 |
| txn_time | Number | Y | - | 1644489139000 | 결제 시각(Unix Timestamp, UTC+0 기준) |
| inservice_item_id | String | Y | - | cp1004 | 게임내 아이템ID |
data (온라인 장바구니 상품)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | String | Y | - | 1234567890 | 스토브 빌링에서 발급한 장바구니 주문번호 |
| products | Array | Y | - | - | 상품정보 |
| products[].tid | String | Y | - | 1234567880 | 스토브 빌링에서 발급한 상품 주문번호 |
| products[].product_id | String | Y | - | p1004 | 스토브 플랫폼에 등록한 상품 코드 |
| products[].quantity | Number | N | 1 | 1 | 개별 상품 수량 |
| products[].product_price | String | Y | - | 1100, 0.99 | 거래 금액 |
| products[].product_currency | String | Y | - | KRW, USD | 해당 금액의 통화 |
| products[].txn_time | Number | Y | - | 1644489139000 | 결제 시각(Unix Timestamp, UTC+0 기준) |
| products[].inservice_item_id | String | Y | - | cp1004 | 게임내 아이템ID |
온라인 상품
{
"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"
}
}
모바일 상품
{
"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
}
}
온라인 장바구니 상품
{
"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
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)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| service_id | String | Y | - | STOVE_XPFWMS | 서비스 아이디 |
Request Body
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| details | ArrayList | Y | - | - | 상세 - 최대 100 개 |
| details[].tid | String | Y | - | 1234567890 | 스토브 빌링에서 발급한 주문번호 |
| details[].bill_platform_type | String | Y | - | MOBILE | 결제 유효성 체크 플랫폼 타입 - MOBILE - SHOP |
| details[].noti_type | String | Y | - | IAP_PURCHASE | 구분 - ONLINE_PURCHASE : 온라인일반상품 구매 - ONLINE_CART_PURCHASE: 온라인장바구니상품 구매 - IAP_PURCHASE: 모바일 일반상품 구매- IAP_SUBSCRIPT : 모바일 구독상품 구매- IAP_OOAP- IAP_PURCHASE: 모바일 OOAP 상품 구매 |
| details[].guid | String | N | - | - | 스토브 회원 GUID - guid가 없는 게임을 제외하고는 필수 |
| details[].member_no | Number | N | - | - | 회원 번호 - guid 가 없는 게임의 경우에만 필수 |
Response
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| code | Integer | Y | - | 0 | 응답 코드 |
| message | String | Y | - | OK | 응답 메시지 |
| data | Object | N | - | - | 응답 값 |
data (온라인 상품, 모바일 상품)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | String | Y | - | 1234567890 | 스토브 빌링에서 발급한 상품 주문번호 |
| product_id | String | Y | - | p1004 | 스토브 플랫폼에 등록한 상품 코드 |
| quantity | Number | N | 1 | 20 | 온라인 상품 (SHOP) 응답 값 |
| product_price | String | Y | - | 1100, 0.99 | 거래 금액 |
| product_currency | String | Y | - | KRW, USD | 해당 금액의 통화 |
| txn_time | Number | Y | - | 1644489139000 | 결제 시각(Unix Timestamp, UTC+0 기준) |
| inservice_item_id | String | Y | - | cp1004 | 게임내 아이템ID |
| guid | String | N | - | 123456 | 모바일 상품 ( MOBILE) 응답 값 |
{
"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
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)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| service_id | String | Y | - | STOVE_XPFWMS | 서비스 아이디 |
Parameter (Query String)
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| bill_platform_type | String | N | - | MOBILE | 비정상 환불 내역 플랫폼 타입 - MOBILE |
| guid | String | N | - | 265265 | 게임 유저 유일키 - member_no / guid 중 하나는 필수 |
| member_no | Long | N | - | 123456 | 회원 번호 - member_no / guid 중 하나는 필수 - guid가 없는 게임은 member_no 사용 |
| character_no | Long | N | - | 624462 | 캐릭터 번호 |
| market_code | String | N | - | GOOGLE_PLAY | 마켓 코드 GOOGLE_PLAY, APPLE_APP_STORE |
Response
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| code | Integer | Y | - | 0 | 응답 코드 |
| message | String | Y | - | OK | 응답 메시지 |
| data | Object | N | - | - | 응답 값 |
data
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| total_count | Int | Y | - | 2 | 조회 조건에 해당하는 총 환불 건수 (list 건수와 동일) |
| list | Array | Y | - | 환불 내역 목록. 환불 내역이 없는 경우 빈 배열()로 반환됩니다. |
list
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | Long | Y | - | 1234567 | 스토브 빌링에서 발급한 주문번호 |
| market_code | String | Y | - | GOOGLE_PLAY | 마켓 코드 MOBILE: GOOGLE_PLAY, APPLE_APP_STORE |
| product_id | String | Y | - | 123456 | 스토브 플랫폼에 등록한 상품 코드 |
| market_product_id | String | Y | - | 123456 | 마켓에 등록된 상품의 코드 |
| market_user_id | String | N | - | 123456 | 마켓 회원 아이디 (현재 STEAM만 제공 = steam_id, 모바일 마켓 미제공 → null) |
| inservice_item_id | String | N | - | cp7892 | 게임 내 아이템 ID |
| user_id | String | Y | - | 265265 | GUID 게임 시 스토브 GUID, 아닐 경우 member_no |
| character_no | Long | Y | - | 123456 | 게임 캐릭터 별로 발급되는 유일키 (STOVE에서 발급) |
| purchase_dt | Long | Y | - | 1699845522000 | 결제 일자 (UTC Timestamp, ms) |
| voided_dt | Long | Y | - | 1699845522000 | 환불 일자 (UTC Timestamp, ms) |
{
"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
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | Long | Y | - | 1609997628158350014 | STOVE에서 결제 완료 시 전달한 주문번호 |
| guid | String | Y | - | 200000006062 | 게임 유저 유일키 |
| market_code | String | Y | - | GOOGLE_PLAY, APPLE_APP_STORE | 환불가능여부를 요청한 마켓코드 (GOOGLE_PLAY: 구글, APPLE_APP_STORE: 애플) |
| product_id | String | Y | - | l_0001 | 스토브 아이템 아이디 |
{
"tid" : 1609997628158350014,
"guid": "200000006062",
"market_code": "GOOGLE_PLAY",
"product_id": "l_0001"
}
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| code | Integer | Y | - | 0 | 응답 코드 |
| message | String | Y | - | 성공 | 응답 메시지 |
| data | JObject | Y | - | - | 회수 판정 결과가 담긴 객체 |
data
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| decision | Integer | Y | - | 0 | 환불승인여부 (0: APPROVE, 1: REJECT) |
| item_status | Integer | Y | - | 0 | 0: 회수가능(아이템 회수), 1: 회수불가 |
{
"code" : 0,
"message":"성공",
"data": {
"decision":0,
"item_status":0
}
}
- 인게임 상점(PC), 스팀 상점
- Request
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | Long | Y | - | 1609997628158350014 | STOVE에서 결제 완료 시 전달한 주문번호 |
| guid | String | Y | - | 200000006062 | 게임 유저 유일키 |
| market_code | String | Y | - | ONLINE | 환불가능여부를 요청한 마켓코드 (ONLINE: PC 온라인/스팀) |
| inservice_item_id | String | Y | - | l_0001 | 게임사 아이템 아이디 |
{
"tid": 1609997628158350014,
"guid": "200000006062",
"market_code": "ONLINE",
"inservice_item_id": "l_0001"
}
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| code | Integer | Y | - | 0 | 응답 코드 |
| message | String | Y | - | 성공 | 응답 메시지 |
| data | JObject | Y | - | - | 회수 판정 결과가 담긴 객체 |
data
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| decision | Integer | Y | - | 0 | 환불승인여부 (0: APPROVE, 1: REJECT) |
| item_status | Integer | Y | - | 0 | 0: 회수가능(아이템 회수), 1: 회수불가 |
{
"code" : 0,
"message":"성공",
"data": {
"decision":0,
"item_status":0
}
}
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | Long | Y | - | 1609997628158350014 | STOVE에서 결제 완료 시 전달한 주문번호 |
| guid | String | Y | - | 200000006062 | 게임 유저 유일키 |
| market_code | String | Y | - | ONLINE_CART | 환불가능여부를 요청한 마켓코드 (ONLINE_CART: 웹 상점 장바구니/묶음 결제) |
| items | Array | Y | - | - | 회수 대상 구매 상품 목록 (BULK 처리) |
items
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | Long | Y | - | 1234567 | 개별 구매 상품의 주문번호 (구매 상세 TID) |
| inservice_item_id | String | Y | - | l_0001 | 게임사 아이템 아이디 |
{
"tid": 1609997628158350014,
"guid": "200000006062",
"market_code": "ONLINE_CART",
"items": [
{ "tid": 1234567, "inservice_item_id": "l_0001" },
{ "tid": 1234568, "inservice_item_id": "l_0002" }
]
}
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| code | Integer | Y | - | 0 | 응답 코드 |
| message | String | Y | - | 성공 | 응답 메시지 |
| data | JObject | Y | - | - | 회수 판정 결과가 담긴 객체 |
data
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| decision | Integer | Y | - | 0 | 환불승인여부 (0: APPROVE, 1: REJECT) |
| items | Array | Y | - | - | 상품별 회수 판정 결과 목록 (BULK 처리) |
items
| Name | Type | Required | Default Value | Example | Description |
|---|---|---|---|---|---|
| tid | Long | Y | - | 1234567 | 개별 구매 상품의 주문번호 |
| item_status | Integer | Y | - | 0 | 0: 회수가능(아이템 회수), 1: 회수불가 |
{
"code": 0,
"message": "성공",
"data": {
"decision": 0,
"items": [
{ "tid": 1234567, "item_status": 0 },
{ "tid": 1234568, "item_status": 0 }
]
}
}
자주 묻는 질문
- 개발자센터 이용/스마일게이트 퍼블리싱 게임 관련: stove.developers@smilegate.com
- 스토브 스토어 입점/스토브 스튜디오 관련: store.support@smilegate.com