Game > Gamebase > Unreal SDK 사용 가이드 > 결제

여기에서는 Unreal에서 인앱 결제 기능을 사용하기 위해 필요한 설정 방법을 알아보겠습니다. Gamebase는 하나의 통합된 결제 API를 제공해 게임에서 손쉽게 많은 스토어의 인앱 결제를 연동할 수 있도록 돕습니다.

Settings

[주의]

Android ONE Store는 v17만을 지원합니다. Android ONE Store v19는 지원을 검토 중으로, 현재는 지원하지 않습니다.

Android나 iOS에서 인앱 결제 기능을 설정하는 방법은 다음 문서를 참고하시기 바랍니다.

Android 결제 설정(엔진 버전 4.24 이하)

  • Epic Games Launcher를 통해 4.24 버전을 설치한 경우, Engine\Build\Android\Java\src\com\android\vending\billing\IInAppBillingService.aidl을 삭제해야 정상적으로 빌드할 수 있습니다.
    • IInAppBillingService.aidl 파일은 Gamebase에서 제공하고 있어 충돌이 발생하여 제거가 필요합니다.
    • 엔진 4.25 이상 버전이나 GitHub에서 엔진을 받은 경우에는 별도로 제거할 필요가 없습니다.

Purchase Flow

아이템 구매는 크게 결제 Flow 와 Consume Flow, 재처리 Flow 로 나누어 볼 수 있습니다. 결제 Flow는 다음과 같은 순서로 구현하시기 바랍니다.

purchase flow

  1. 이전 결제가 정상적으로 종료되지 못한 경우 재처리가 동작하지 않으면 결제가 실패합니다. 그러므로 결제 전에 RequestItemListOfNotConsumed를 호출하여 재처리를 동작시켜 미지급된 아이템이 있으면 Consume Flow 를 진행합니다.
  2. 게임 클라이언트에서는 Gamebase SDK의 RequestPurchase를 호출하여 결제를 시도합니다.
  3. 결제가 성공했다면 RequestItemListOfNotConsumed를 호출하여 미소비 결제 내역을 확인한 후 지급할 아이템이 존재한다면 Consume Flow 를 진행합니다.

Consume Flow

미소비 결제 내역 목록에 값이 있으면 다음과 같은 순서로 Consume Flow 를 진행하시기 바랍니다.

[주의]

아이템이 중복 지급되는 일이 발생하지 않도록, 게임 서버에서 반드시 중복 지급 여부를 체크하시기 바랍니다.

purchase flow

  1. 게임 클라이언트가 게임 서버에 결제 아이템에 대한 consume(소비)을 요청합니다.
    • UserID, gamebaseProductId, paymentSeq, purchaseToken 을 전달합니다.
  2. 게임 서버는 게임 DB에 이미 동일한 paymentSeq 로 아이템을 지급한 이력이 있는지 확인합니다.
    • 2-1. 아직 아이템을 지급하지 않았다면 UserID 에 gamebaseProductId 에 해당하는 아이템을 지급합니다.
    • 2-2. 아이템 지급 후 게임 DB에 UserID, gamebaseProductId, paymentSeq, purchaseToken을 저장하여 중복 지급 방지 또는 재지급을 할 수 있도록 합니다.
  3. 아이템 지급 여부와 무관하게 게임 서버는 Gamebase 서버의 consume(소비) API를 호출하여 아이템 지급을 완료합니다.

Retry Transaction Flow

  • 스토어 결제에는 성공했으나 오류가 발생해 정상 종료되지 못하는 경우가 있습니다.
  • RequestItemListOfNotConsumed를 호출하여 재처리를 동작시켜 미지급된 아이템이 있으면 Consume Flow 를 진행하세요.
  • 재처리는 다음과 같은 시점에 호출할 것을 권장합니다.
    • 로그인 완료 후.
    • 결제 전.
    • 게임 내 상점(또는 로비) 진입시.
    • 유저 프로필 또는 우편함 확인시.

Purchase Item

구매하고자 하는 아이템의 gamebaseProductId를 이용해 다음의 API를 호출하여 구매를 요청합니다. 게임 유저가 구매를 취소하는 경우 PURCHASE_USER_CANCELED 오류가 반환됩니다.

API

Supported Platforms UNREAL_IOS UNREAL_ANDROID

void RequestPurchase(const FString& gamebaseProductId, const FGamebasePurchasableReceiptDelegate& onCallback);
void RequestPurchase(const FString& gamebaseProductId, const FString& payload, const FGamebasePurchasableReceiptDelegate& onCallback);

// Legacy API
void RequestPurchase(int64 itemSeq, const FGamebasePurchasableReceiptDelegate& onCallback);

Example

void Sample::RequestPurchase(const FString& gamebaseProductId)
{
    IGamebase::Get().GetPurchase().RequestPurchase(gamebaseProductId, FGamebasePurchasableReceiptDelegate::CreateLambda(
        [](const FGamebasePurchasableReceipt* purchasableReceipt, const FGamebaseError* error)
    {
        if (Gamebase::IsSuccess(error))
        {
            UE_LOG(GamebaseTestResults, Display, TEXT("RequestPurchase succeeded. (gamebaseProductId= %s, price= %f, currency= %s, paymentSeq= %s, purchaseToken= %s)"),
                *purchasableReceipt->gamebaseProductId, purchasableReceipt->price, *purchasableReceipt->currency,
                *purchasableReceipt->paymentSeq, *purchasableReceipt->purchaseToken);
        }
        else
        {
            if (error->code == GamebaseErrorCode::PURCHASE_USER_CANCELED)
            {
                UE_LOG(GamebaseTestResults, Display, TEXT("User canceled purchase."));
            }
            else
            {
                // Check the error code and handle the error appropriately.
                UE_LOG(GamebaseTestResults, Display, TEXT("RequestPurchase failed. (error: %d)"), error->code);
            }

        }
    }));
}

void Sample::RequestPurchaseWithPayload(const FString& gamebaseProductId)
{
    FString userPayload = TEXT("{\"description\":\"This is example\",\"channelId\":\"delta\",\"characterId\":\"abc\"}");

    IGamebase::Get().GetPurchase().RequestPurchase(gamebaseProductId, userPayload, FGamebasePurchasableReceiptDelegate::CreateLambda(
        [](const FGamebasePurchasableReceipt* purchasableReceipt, const FGamebaseError* error)
    {
        if (Gamebase::IsSuccess(error))
        {
            UE_LOG(GamebaseTestResults, Display, TEXT("RequestPurchase succeeded. (gamebaseProductId= %s, price= %f, currency= %s, paymentSeq= %s, purchaseToken= %s)"),
                *purchasableReceipt->gamebaseProductId, purchasableReceipt->price, *purchasableReceipt->currency,
                *purchasableReceipt->paymentSeq, *purchasableReceipt->purchaseToken);

            FString payload = purchasableReceipt->payload;
        }
        else
        {
            if (error->code == GamebaseErrorCode::PURCHASE_USER_CANCELED)
            {
                UE_LOG(GamebaseTestResults, Display, TEXT("User canceled purchase."));
            }
            else
            {
                // Check the error code and handle the error appropriately.
                UE_LOG(GamebaseTestResults, Display, TEXT("RequestPurchase failed. (error: %d)"), error->code);
            }
        }
    }));
}

VO

USTRUCT()
struct FGamebasePurchasableReceipt
{
    GENERATED_USTRUCT_BODY()

    // 구매한 아이템의 상품 ID 입니다.
    UPROPERTY()
    FString gamebaseProductId;

    // itemSeq 로 상품을 구매하는 Legacy API용 식별자 입니다.
    UPROPERTY()
    int64 itemSeq;

    // 구매한 상품의 가격 입니다.
    UPROPERTY()
    float price;

    // 통화 코드 입니다.
    UPROPERTY()
    FString currency;

    // 결제 식별자입니다.
    // purchaseToken 과 함께 'Consume' 서버 API 를 호출하는데 사용하는 중요한 정보입니다.
    // Consume API : https://docs.toast.com/en/Game/Gamebase/en/api-guide/#purchase-iap
    // 주의 : Consume API 는 게임 서버에서 호출하세요! 
    UPROPERTY()
    FString paymentSeq;

    // 결제 식별자입니다.
    // paymentSeq 와 함께 'Consume' 서버 API 를 호출하는데 사용하는 중요한 정보입니다.
    // Consume API 에서는 'accessToken' 라는 이름의 파라메터로 전달해야 합니다.
    // Consume API : https://docs.toast.com/en/Game/Gamebase/en/api-guide/#purchase-iap
    // 주의 : Consume API 는 게임 서버에서 호출하세요! 
    UPROPERTY()
    FString purchaseToken;

    // Google, Apple 과 같이 스토어 콘솔에 등록된 상품 ID 입니다.
    UPROPERTY()
    FString marketItemId;

    // 상품 타입으로, 다음 값들이 올 수 있습니다.
    // * UNKNOWN : 인식 불가능한 타입. Gamebase SDK 를 업데이트 하거나 Gamebase 고객센터로 문의하세요.
    // * CONSUMABLE : 소비성 상품.
    // * AUTO_RENEWABLE : 구독형 상품.
    // * CONSUMABLE_AUTO_RENEWABLE : 구독형 상품을 구매한 유저에게 정기적으로 소비가 가능한 상품을 지급하고자 하는 경우 사용되는 '소비가 가능한 구독 상품'.
    UPROPERTY()
    FString productType;

    // 상품을 구매했던 User ID.
    // 상품을 구매하지 않은 User ID 로 로그인 한다면 구매한 아이템을 획득할 수 없습니다.
    UPROPERTY()
    FString userId;

    // 스토어의 결제 식별자 입니다.
    UPROPERTY()
    FString paymentId;

    // 구독 상품은 갱신 될때마다 paymentId 가 변경됩니다.
    // 이 필드는 맨 처음 구독 상품을 결제 했을때의 paymentId 를 알려줍니다.
    // 스토어에 따라, 결제 서버 상태에 따라 값이 존재하지 않을 수 있으므로
    // 항상 유효한 값을 보장하지는 않습니다.
    UPROPERTY()
    FString originalPaymentId;

    // 상품을 구매했던 시각입니다.(epoch time)
    UPROPERTY()
    int64 purchaseTime;

    // 구독이 종료되는 시각입니다.(epoch time)
    UPROPERTY()
    int64 expiryTime;

    // Gamebase.Purchase.requestPurchase API 호출시 payload 로 전달했던 값입니다.
    //
    // 이 필드는 예를 들어 동일한 User ID 로 구매 했음에도 게임 채널, 캐릭터 등에 따라
    // 상품 구매 및 지급을 구분하고자 하는 경우 등
    // 게임에서 필요로 하는 다양한 추가 정보를 담기 위한 목적으로 활용할 수 있습니다.
    UPROPERTY()
    FString payload;
};

List Purchasable Items

아이템 목록을 조회하려면 다음 API를 호출합니다. 콜백으로 반환되는 목록 안에는 각 아이템들에 대한 정보가 있습니다.

API

Supported Platforms UNREAL_IOS UNREAL_ANDROID

void RequestItemListPurchasable(const FGamebasePurchasableItemListDelegate& onCallback);

Example

void Sample::RequestItemListPurchasable()
{
    IGamebase::Get().GetPurchase().RequestItemListPurchasable(FGamebasePurchasableItemListDelegate::CreateLambda(
        [](const TArray<FGamebasePurchasableItem>* purchasableItemList, const FGamebaseError* error)
    {
        if (Gamebase::IsSuccess(error))
        {
            UE_LOG(GamebaseTestResults, Display, TEXT("RequestItemListPurchasable succeeded."));

            for (const FGamebasePurchasableItem& purchasableItem : *purchasableItemList)
            {
                UE_LOG(GamebaseTestResults, Display, TEXT(" - gamebaseProductId= %s, price= %f, itemName= %s, itemName= %s, marketItemId= %s"),
                    *purchasableItem.gamebaseProductId, purchasableItem.price, *purchasableItem.currency, *purchasableItem.itemName, *purchasableItem.marketItemId);
            }
        }
        else
        {
            UE_LOG(GamebaseTestResults, Display, TEXT("RequestItemListPurchasable failed. (error: %d)"), error->code);
        }
    }));
}

VO

USTRUCT()
struct FGamebasePurchasableItem
{
    GENERATED_USTRUCT_BODY()

    // Gamebase 콘솔에 등록된 상품 ID 입니다.
    // Gamebase.Purchase.requestPurchase API 로 상품을 구매할때 사용됩니다.
    UPROPERTY()
    FString gamebaseProductId;

    // itemSeq 로 상품을 구매하는 Legacy API용 식별자 입니다.
    UPROPERTY()
    int64 itemSeq;

    // 상품의 가격 입니다.
    UPROPERTY()
    float price;

    // 통화 코드 입니다.
    UPROPERTY()
    FString currency;

    // Gamebase 콘솔에 등록된 상품 이름입니다.
    UPROPERTY()
    FString itemName;

    // Google, Apple 과 같이 스토어 콘솔에 등록된 상품 ID 입니다.
    UPROPERTY()
    FString marketItemId;

    // 상품 타입으로, 다음 값들이 올 수 있습니다.
    // * UNKNOWN : 인식 불가능한 타입. Gamebase SDK 를 업데이트 하거나 Gamebase 고객센터로 문의하세요.
    // * CONSUMABLE : 소비성 상품.
    // * AUTORENEWABLE : 구독형 상품.
    // * CONSUMABLE_AUTO_RENEWABLE : 구독형 상품을 구매한 유저에게 정기적으로 소비가 가능한 상품을 지급하고자 하는 경우 사용되는 '소비가 가능한 구독 상품'.
    UPROPERTY()
    FString productType;

    // 통화 기호가 포함된 현지화 된 가격 정보입니다.
    UPROPERTY()
    FString localizedPrice;

    // 스토어 콘솔에 등록된 현지화된 상품 이름 입니다.
    UPROPERTY()
    FString localizedTitle;

    // 스토어 콘솔에 등록된 현지화된 상품 설명 입니다.
    UPROPERTY()
    FString localizedDescription;

    // Gamebase 콘솔에서 해당 상품의 '사용 여부'를 나타냅니다.
    UPROPERTY()
    bool isActive;
};

List Non-Consumed Items

아이템을 구매했지만, 정상적으로 아이템이 소비(배송, 지급)되지 않은 미소비 결제 내역을 요청합니다. 미결제 내역이 있는 경우에는 게임 서버(아이템 서버)에 요청하여, 아이템을 배송(지급)하도록 처리해야 합니다.

API

Supported Platforms UNREAL_IOS UNREAL_ANDROID

void RequestItemListOfNotConsumed(const FGamebasePurchasableReceiptListDelegate& onCallback);

Example

void Sample::RequestItemListOfNotConsumed()
{
    IGamebase::Get().GetPurchase().RequestItemListOfNotConsumed(FGamebasePurchasableItemListDelegate::CreateLambda(
        [](const TArray<FGamebasePurchasableItem>* purchasableItemList, const FGamebaseError* error)
    {
        if (Gamebase::IsSuccess(error))
        {
            // Should Deal With This non-consumed Items.
            // Send this item list to the game(item) server for consuming item.

            UE_LOG(GamebaseTestResults, Display, TEXT("RequestItemListOfNotConsumed succeeded."));

            for (const FGamebasePurchasableItem& purchasableItem : *purchasableItemList)
            {
                UE_LOG(GamebaseTestResults, Display, TEXT(" - gamebaseProductId= %s, price= %f, itemName= %s, itemName= %s, marketItemId= %s"),
                    *purchasableReceipt.gamebaseProductId, purchasableItem.price, *purchasableItem.currency, *purchasableItem.itemName, *purchasableItem.marketItemId);
            }
        }
        else
        {
            UE_LOG(GamebaseTestResults, Display, TEXT("RequestItemListOfNotConsumed failed. (error: %d)"), error->code);
        }
    }));
}

List Actived Subscriptions

현재 사용자 ID 기준으로 활성화된 구독 목록을 조회합니다. 결제가 완료된 구독 상품(자동 갱신형 구독, 자동 갱신형 소비성 구독 상품)은 만료되기 전까지 계속 조회할 수 있습니다. 사용자 ID가 같다면 Android와 iOS에서 구매한 구독 상품이 모두 조회됩니다.

[주의]

현재 구독 상품은 Android의 경우 Google Play 스토어만 지원합니다.

API

Supported Platforms UNREAL_IOS UNREAL_ANDROID

void RequestActivatedPurchases(const FGamebasePurchasableReceiptListDelegate& onCallback);

Example

void Sample::RequestActivatedPurchases()
{
    IGamebase::Get().GetPurchase().RequestActivatedPurchases(FGamebasePurchasableReceiptListDelegate::CreateLambda(
        [](const TArray<FGamebasePurchasableReceipt>* purchasableReceiptList, const FGamebaseError* error)
    {
        if (Gamebase::IsSuccess(error))
        {
            UE_LOG(GamebaseTestResults, Display, TEXT("RequestActivatedPurchases succeeded."));

            for (const FGamebasePurchasableReceipt& purchasableReceipt : *purchasableReceiptList)
            {
                UE_LOG(GamebaseTestResults, Display, TEXT(" - gamebaseProductId= %s, price= %f, currency= %s, paymentSeq= %s, purchaseToken= %s"),
                    *purchasableReceipt.gamebaseProductId, purchasableReceipt.price, *purchasableReceipt.currency, *purchasableReceipt.paymentSeq, *purchasableReceipt.purchaseToken);
            }
        }
        else
        {
            UE_LOG(GamebaseTestResults, Display, TEXT("RequestActivatedPurchases failed. (error: %d)"), error->code);
        }
    }));
}

Error Handling

Error Error Code Description
PURCHASE_NOT_INITIALIZED 4001 Purchase 모듈이 초기화되지 않았습니다.
gamebase-adapter-purchase-IAP 모듈을 프로젝트에 추가했는지 확인해 주세요.
PURCHASE_USER_CANCELED 4002 게임 유저가 아이템 구매를 취소하였습니다.
PURCHASE_NOT_FINISHED_PREVIOUS_PURCHASING 4003 구매 로직이 아직 완료되지 않은 상태에서 API가 호출되었습니다.
PURCHASE_NOT_ENOUGH_CASH 4004 해당 스토어의 캐시가 부족해 결제할 수 없습니다.
PURCHASE_INACTIVE_PRODUCT_ID 4005 해당 상품이 활성화 상태가 아닙니다.
PURCHASE_NOT_EXIST_PRODUCT_ID 4006 존재하지 않는 GamebaseProductID 로 결제를 요청하였습니다.
PURCHASE_LIMIT_EXCEEDED 4007 월 구매 한도를 초과했습니다.
PURCHASE_NOT_SUPPORTED_MARKET 4010 지원하지 않는 스토어입니다.
선택 가능한 스토어는 AS(App Store), GG(Google), ONESTORE, GALAXY 입니다.
PURCHASE_EXTERNAL_LIBRARY_ERROR 4201 IAP 라이브러리 오류입니다.
DetailCode를 확인하세요.
PURCHASE_UNKNOWN_ERROR 4999 정의되지 않은 구매 오류입니다.
전체 로그를 고객 센터에 올려 주시면 가능한 한 빠르게 답변 드리겠습니다.
  • 전체 오류 코드는 다음 문서를 참고하시기 바랍니다.

PURCHASE_EXTERNAL_LIBRARY_ERROR

  • 이 오류는 IAP 모듈에서 발생한 오류입니다.
  • 오류 코드를 확인하는 방법은 다음과 같습니다.
GamebaseError* gamebaseError = error; // GamebaseError object via callback

if (Gamebase::IsSuccess(error))
{
    // succeeded
}
else
{
    UE_LOG(GamebaseTestResults, Display, TEXT("code: %d, message: %s"), error->code, *error->message);

    GamebaseInnerError* moduleError = gamebaseError.error; // GamebaseError.error object from external module
    if (moduleError.code != GamebaseErrorCode::SUCCESS)
    {
        UE_LOG(GamebaseTestResults, Display, TEXT("moduleErrorCode: %d, moduleErrorMessage: %s"), moduleError->code, *moduleError->message);
    }
}
TOP