PG 결제

IAP v4는 PC 및 모바일 환경에서 PG 결제를 지원합니다.

PG 결제를 적용하기에 앞서 PG 결제 정책을 확인하고, PG 결제 하이브 콘솔 가이드 사전 작업 내용에 따라 하이브 콘솔에 필요한 정보를 등록하세요.

PG 결제 특징¶

PG 결제의 주요 특징은 아래와 같습니다.

• PG 결제는 IAP v4와 PG 결제 API를 기반으로 동작하며, 결제 대행사(PG)에서 제공하는 웹 브라우저를 통해 비동기 방식으로 처리됩니다.

• 지급이 완료된 주문은 반드시 transactionFinish(marketPid) API를 통해 상품 지급 완료 처리를 해야 합니다.

  • 결제는 완료되었으나 지급 완료 처리가 되지 않은 상품을 재구매하고자 할 때에는 결제가 진행되지 않습니다. 이전 구매 상품의 지급 완료 처리 후에 재구매할 수 있습니다.

  • 결제를 완료하지 않은 상태에서 여러 개의 결제창을 띄워 결제를 시도하는 경우와 같이 지급 완료 처리되지 않은 상품의 추가 구매를 시도하면 최초 1건의 결제만 완료되며, 나머지 구매 건은 결제가 되더라도 자동 취소됩니다.

  • 지급 완료 처리 요청을 하더라도 게임 서버의 판단에 따라 결제가 취소될 수 있습니다.

PC PG 결제¶

PC 환경에서는 PG 결제를 진행하면 아래와 같은 결제 요청 화면이 새 창으로 노출됩니다.

모바일 PG 결제¶

모바일 환경에서도 PG 결제를 진행하면 인앱 웹뷰를 통해 결제 요청 화면이 노출됩니다.

사전 준비 사항¶

모바일 PG 결제를 사용하려면 프로젝트에 HiveStore 모듈 추가 가 필요합니다. 각 SDK의 개발 엔진 및 타깃 OS에 따라 아래 안내를 참고하세요.

SDK Native Android¶

모듈 수준 build.gradle 파일에 HiveStore 마켓 라이브러리를 추가합니다.

implementation "com.com2us.android.hive:hive-iapv4-market-hivestore" // Hive Store(PG)

SDK Native iOS¶

프로젝트 디렉토리의 Podfile 에 인앱 결제 프레임워크와 PG(HiveStore) 프레임워크를 추가합니다.

pod 'HiveIAPV4', $HIVE_SDK_VERSION
pod 'HiveIAPV4HiveStore', $HIVE_SDK_VERSION // Hive Store(PG)

Unity¶

1. Unity 에디터에서 Hive > ExternalDependency 메뉴를 클릭합니다.
2. Market Settings 에서 Hive Store 를 선택합니다.

Unreal¶

1. 언리얼 에디터 메뉴에서 Edit > Project Settings 를 클릭합니다.
2. 좌측 패널에서 Hive SDK > Dependency – Android / Hive SDK > Dependency – iOS 를 선택합니다.
3. Market 에서 Hive Store 를 선택합니다.

모바일 PG 결제 정책 안내¶

모바일 PG 결제는 플랫폼별 정책에 따라 지원 범위가 제한됩니다.

iOS 구현 시 주의사항¶

iOS에서는 Apple의 App Review Guidelines (Guideline 3.1.1, 3.1.1(a), 3.1.3)에 따라 미국 스토어프론트에서만 PG 결제를 지원합니다. Apple은 2025년 5월 미국 법원 판결에 따라 가이드라인을 업데이트하여, 미국 스토어프론트에서는 인앱 결제(IAP) 이외의 결제 수단으로 유도하는 버튼, 외부 링크, CTA(Call to Action) 등을 별도의 Entitlement 없이 노출할 수 있도록 허용하고 있습니다.

• 미국 외 스토어프론트에서는 앱 내에서 인앱 결제 외 결제 수단으로 유도하는 버튼이나 링크를 노출하면 Apple 심사에서 리젝됩니다.
• 사용자의 스토어프론트 지역에 따라 PG 결제 진입점 노출 여부를 분기 처리하는 것을 권장합니다.

모바일 PG 연동 플로우¶

모바일 환경에서 PG 결제를 연동하는 흐름은 아래와 같습니다.

결제 및 영수증 처리 흐름¶

PC와 모바일 PG 결제의 영수증 처리 흐름은 동일하며, 모바일의 경우 구매 요청 전에 마켓을 Hive Store로 변경하는 단계가 추가됩니다.

1. (모바일만 해당) IAPV4.setMarketSelection(IAPV4Type.hiveStore)를 호출해 마켓을 Hive Store로 변경

2. IAPV4.purchase(marketPid, iapPayload, onIAPV4PurchaseCB)를 호출해 구매 요청

   Warning

   하이브 콘솔 빌링 > 결제 환경 설정 > PG 설정 > 부가 기능 설정에서 결제 완료 정보를 위한 URL을 등록한 경우, 이 URL을 먼저 삭제해야 합니다.

3. 상품 구매를 정상적으로 완료하면, onIAPV4PurchaseCB 콜백으로 영수증 정보(bypassInfo)를 전달받음

4. 게임 클라이언트는 이 영수증 정보를 게임 서버로 전달

5. 게임 서버는 영수증 검증 API를 호출해 이 영수증 정보를 검증

6. 영수증 검증을 성공적으로 완료하면 IAPV4.transactionFinish를 호출해 상품 지급 처리를 완료

위 3번 단계에서 onIAPV4PurchaseCB 콜백으로 구매가 정상적으로 완료되었음을 알려주는 영수증 정보를 받지 못했다면, IAPV4.restore를 호출해 미지급된 아이템에 대한 영수증 정보를 다시 요청합니다. 그 이후 4~6번 단계를 따라 영수증 검증 및 상품 지급 처리를 완료합니다.

다중 수량 구매¶

PG 결제는 다중 수량 구매를 지원합니다. 구매 요청 시 수량을 지정하도록 하여, 한 번의 결제 시에 동일한 게임 앱 내 상품을 두 개 이상 구매할 수 있습니다.

Hive SDK에서는 수량을 지정할 수 있는 quantity 파라미터가 포함된 hive.IAPV4.purchase(marketPid, iapPayload, quantity, onIAPV4PurchaseCB)를 호출합니다.

다중 수량 구매를 요청하는 예제 코드는 아래와 같습니다.

using hive;    
    String marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
    String iapPayload = "{YOUR_CUSTOM_PAYLOAD}";
    int quantity = 3;

    IAPV4.purchase(marketPid, iapPayload, quantity, (ResultAPI result, IAPV4Receipt receipt) => {    
    if (result.isSuccess()) {    
             // TODO: Request verification of receipt with received receipt    
         }    
});

#include "HiveIAPV4.h"

FString MarketPid = TEXT("YOUR_PRODUCT_MARKET_PID");
FString IapPayload = TEXT("YOUR_CUSTOM_PAYLOAD");
int32 Quantity = 3;

FHiveIAPV4::Purchase(MarketPid, IapPayload, Quantity, FHiveIAPV4OnPurchaseDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveIAPV4Receipt& Receipt) {
        if (Result.IsSuccess()) {
                // API 호출 성공
        }
}));

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    string marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
    string iapPayload = "{YOUR_CUSTOM_PAYLOAD}";
    int quantity = 3;
    IAPV4::purchase(marketPid, iapPayload, quantity, [=](ResultAPI const & result, IAPV4Receipt const & receipt) {    
         if (result.isSuccess()) {    
             // TODO: Request verification of receipt with received receipt    
         }    
});

import com.hive.IAPV4    
    import com.hive.ResultAPI    
    val marketPid = "{YOUR_PRODUCT_MARKET_PID}"    
    val iapPayload = "{YOUR_CUSTOM_PAYLOAD}"
    val quantity = 3
    IAPV4.purchase(marketPid, iapPayload, quantity, object : IAPV4.IAPV4PurchaseListener {    
         override fun onIAPV4Purchase(result: ResultAPI, iapV4Receipt: IAPV4.IAPV4Receipt?) {    
             if (result.isSuccess) {    
                 // call successful    
             }    
         }    
})

import com.hive.IAPV4;    
    import com.hive.ResultAPI;    
    String marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
    String iapPayload = "{YOUR_CUSTOM_PAYLOAD}";
    int quantity = 3;
    IAPV4.INSTANCE.purchase(marketPid, iapPayload, quantity, (result, iapV4Receipt) -> {    
         if (result.isSuccess()) {    
             // call successful    
         }    
});

import HIVEService    
    let marketPid = "{YOUR_PRODUCT_MARKET_PID}"    
    let iapPayload = "{YOUR_CUSTOM_PAYLOAD}"
    let quantity = 3

    HIVEIAPV4.purchase(marketPid, iapPayload, quantity) { result, receipt in    
         if result.isSuccess() {    
             // TODO: Request verification of receipt with received receipt    
         }    
}

#import <HIVEService/HIVEService-Swift.h>

NSString *marketPid = @"{YOUR_PRODUCT_MARKET_PID}";
NSString *iapPayload = @"{YOUR_CUSTOM_PAYLOAD}";
NSNumber quantity = 3;

[HIVEIAPV4 purchase: marketPid iapPayload: iapPayload quantity handler: ^(HIVEResultAPI *result, HIVEIAPV4Receipt *receipt) {
    if ([result isSuccess]) {
        // TODO: Request verification of receipt with received receipt
    }
}];