2단계. 상품 목록 조회

상품명, 가격, 할인 정보 등 Hive 콘솔에 등록된 PG 상품 정보를 조회합니다. 사용자에게 현재 선택할 수 있는 상품 목록과 정확한 금액을 표시할 때 사용하세요.

PG 상품 정보 조회

Hive 콘솔에 등록된 PG 상품의 상세 정보를 조회합니다. 조회한 상품 정보를 사용자에게 표시하세요.

FetchPgProductsAsync

PG 상품 목록 조회를 구현하려면 Hive Axyl SDK가 제공하는 FetchPgProductsAsync()를 호출하세요. PG 결제로 판매하는 상품 목록을 서비스 표준 형식(Single Standard)으로 반환합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	ProductPg	Required	조회 조건(상품 유형·마켓 등)을 담은 요청 데이터입니다.
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 멱등키·취소 토큰·요청 정책을 지정하며, 생략하면 기본값이 사용됩니다.

ProductPg

필드명	타입	필수 여부	설명
AppVersion	string	Optional	앱 버전입니다. 예: 1.0.0
Country	string	Required	국가 정보입니다. 예: KR
Currency	string	Required	통화입니다. 예: KRW
Language	string	Required	언어입니다. 예: ko
ProductType	string	Optional	상품 유형입니다. 예: consumable
ProviderId	ProductPgProviderId (enum)	Required	마켓 식별자입니다. PG 상품 조회 전용 요청이므로 Pg만 지정합니다.
ServerId	string	Optional	Hive 콘솔 앱 서버를 따라 앱 정보 > 앱 서버에서 앱 서버를 등록한 뒤 앱 서버 탭에서 확인하는 서버 ID입니다. 예: server01

호출 예시

PaymentsFetchPgProductsResult의 성공 결과와 이 메서드에서 정의한 도메인별 결과(Outcome)는 아래 예시와 응답 상태에서 확인합니다. 요청 수행이 불가능한 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

Unity

using Hive.Axyl.Payments;
using Hive.Axyl.Core;

// payments: 초기화 시 등록된 IPaymentsService (자세한 획득은 [모듈 설치 및 초기화](../init.md) 참고)
IPaymentsService payments = HiveCore.Resolve<IPaymentsService>();

// 조회 조건을 담은 요청 객체를 생성합니다.
var request = new ProductPg
{
    ProductType = "consumable",
    ProviderId = ProductPgProviderId.Pg,
    Country = "KR",
    Currency = "KRW",
    Language = "ko"
};

PaymentsFetchPgProductsResult result = await payments.FetchPgProductsAsync(request);

switch (result)
{
    case PaymentsFetchPgProductsResult.Success success:
        // 표준 형식으로 정제된 상품 목록으로 상점 화면을 구성합니다.
        foreach (var product in success.Data.Products)
        {
            Debug.Log($"{product.ProductId}: {product.Title} ({product.DisplayPrice})");
        }
        break;

    // 요청 검증 실패 결과(Outcome) 처리
    case PaymentsFetchPgProductsResult.PaymentBadRequest:
    case PaymentsFetchPgProductsResult.PaymentInvalidParameter:
        // 요청 필드와 필수값을 점검하세요.
        break;

    // 공통 Failure 처리
    case PaymentsFetchPgProductsResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 처리하지 않은 결과 및 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 PaymentsFetchPgProductsResult.Success의 Data(ProductResponseData)에 결과가 담깁니다.

필드명	타입	필수 여부	설명
Data.AppVersion	string	Optional	앱 버전입니다.
Data.Country	string	Optional	국가 정보입니다.
Data.Currency	string	Optional	통화입니다.
Data.Language	string	Required	언어입니다.
Data.Products	IReadOnlyList<ProductProducts>	Optional	표준 형식으로 정제된 상품 정보 목록입니다.
Data.ProviderId	ProductProviderId (enum)	Required	마켓 식별자입니다. 이 응답에서는 Pg가 반환됩니다.
Data.Meta	string	Optional	응답 메타 정보입니다. 없으면 null입니다.

ProductProducts

필드명	타입	필수 여부	설명
Currency	string	Optional	통화입니다. 예: KRW
Description	string	Optional	상품 설명입니다.
DisplayOriginalPrice	string	Optional	화면 표시용 할인 전 가격입니다. 예: ₩1,100
DisplayPrice	string	Optional	화면 표시용 가격입니다. 예: 1,200 KRW
OriginalPrice	decimal	Optional	할인 전 가격입니다. 통화에 따라 소수점이 포함될 수 있습니다. 예: 1100 또는 11.00
Price	decimal	Optional	가격입니다. 통화에 따라 소수점이 포함될 수 있습니다. 예: 1200 또는 9.99
ProductId	string	Optional	상품의 고유 식별자(PID)입니다.
ProductType	string	Optional	상품 유형입니다. subscription(구독), consumable(소모성)
Title	string	Optional	상품 제목입니다. 예: 1000 Gold

응답 예시

Unity

// Success 분기에서 success.Data 예시
// success.Data.ProviderId = ProductProviderId.Pg
// success.Data.Currency = "KRW"
// success.Data.Products[0].ProductId = "com.game.product1"
// success.Data.Products[0].Title = "1000 Gold"
// success.Data.Products[0].Price = 1200.0
// success.Data.Products[0].DisplayPrice = "1,200 KRW"
// success.Data.Products[0].ProductType = "consumable"

응답 상태

아래 표에는 PaymentsFetchPgProductsResult의 성공 결과와 이 메서드에서 정의한 도메인별 결과(Outcome)를 정리했습니다. 요청 수행이 불가능한 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

응답 케이스	설명	앱 클라이언트 대응
Success	상품 목록 조회에 성공했습니다. Data에 표준 형식 상품 목록이 담깁니다.	상품 목록으로 상점 화면 구성
PaymentBadRequest	요청을 처리할 수 없습니다.	요청 값과 호출 조건을 점검
PaymentInvalidParameter	유효하지 않은 파라미터입니다.	요청 필드 값을 점검 후 재요청
UnknownOutcome	SDK가 알 수 없는 도메인별 결과입니다.	실패로 처리하고 결과 코드를 기록
Failure	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

다음 단계

상품을 구매합니다.