3단계. 상품 구매

사용자가 선택한 상품에 대해 Steam 결제 창을 열고 구매 프로세스를 진행한 후 결제 완료 신호를 수신합니다.

아래 과정을 따라 Steam에서 상품 구매를 진행합니다.

1. 인앱 상점 UI 노출

앱에서 인앱 상점 UI를 구현하고 사용자에게 노출합니다. 사용자가 상품을 선택하면 결제 버튼을 누를 수 있도록 합니다. 사용자가 결제 버튼을 누르면 다음 단계로 진행합니다.

2. 선택: 구매 사전 정보 저장

사용자가 결제 버튼을 누른 뒤 Steam Overlay 결제창을 열기 전에 구매 시도 정보를 저장합니다. 전체 흐름은 구매 정보 기록을 참조하세요. 이 단계는 선택 사항입니다.

CreatePrePurchaseAsync

CreatePrePurchaseAsync()는 상품, 결제 예정 금액, 통화, 국가와 언어, 앱 서버, IapPayload를 사전 구매 추적 레코드로 저장합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	PrePurchase	Required	구매 사전 정보 저장 요청 데이터 객체입니다.
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 멱등키·취소 토큰·요청 정책을 지정하며, 생략하면 기본값이 사용됩니다.

PrePurchase

필드명	타입	필수 여부	설명
`Country`	string	Required	사용자의 국가 코드(ISO 3166-1 두 자리)를 전달합니다
`Currency`	string	Required	결제 통화(ISO 4217 세 자리)를 전달합니다. 2단계. 상품 목록 조회에서 조회한 상품의 통화 값을 사용합니다
`Language`	string	Required	언어 코드(ISO 639-1 두 자리)를 전달합니다
`Price`	decimal	Required	결제 예정 금액입니다. 통화에 따라 소수점이 포함될 수 있습니다. 2단계. 상품 목록 조회에서 조회한 상품의 가격 값을 전달합니다
`ProductId`	string	Required	사용자가 선택한 인앱 상품의 고유 식별자입니다. 2단계. 상품 목록 조회에서 조회한 Product ID를 전달합니다
`ProviderId`	PrePurchaseProviderId	Required	마켓·결제 수단 식별자(enum)입니다. Steam 결제 전용 요청이므로 `Steam`만 지정합니다.
`ServerId`	string	Optional	Hive 콘솔 앱 서버를 따라 `앱 정보 > 앱 서버`에서 앱 서버를 등록한 뒤 앱 서버 탭에서 확인하는 서버 ID
`AccountUuid`	string	Optional	로그인한 사용자의 `playerId`로 생성한 UUIDv5 값입니다. 결제를 시작하기 전에 전달합니다. AccountUuid 생성을 참조하세요.
`IapPayload`	string	Optional	개발자가 마켓 결제 시 첨부하는 페이로드(JSON 문자열). 구매 완료 후 앱 서버 콜백에 그대로 전달됩니다.
`RequestDate`	DateTimeOffset	Optional	요청 시각(UTC)입니다. 생략하면 서버의 현재 시각을 사용합니다.

IapPayload 사용 예시

PrePurchase의 IapPayload에는 구매 완료 후 발급되는 영수증에 앱별 데이터를 담을 수 있습니다. 아래는 IapPayload를 활용하는 한 가지 예입니다.

예를 들어 사용자 프로필이 A, B, C 세 가지인 모바일 앱에서 사용자가 A 프로필로 앱 내 상품을 구매했다고 가정합니다. 이때 IapPayload에 {"character": "A"}와 같은 JSON 문자열을 담아 구매를 요청하면, 결제가 정상적으로 완료됐을 때 이 값이 구매 영수증에 포함되어 앱에 전달됩니다.

결제는 완료됐지만 네트워크 오류로 상품을 지급하지 못한 경우에는 지급 실패 건을 조회하고 해당 영수증을 다시 검증한 후 상품을 지급해야 합니다. 이때 사용자가 보유한 A, B, C 프로필 중 지급할 프로필을 알아야 합니다. 구매 영수증에 포함된 IapPayload의 {"character": "A"} 정보를 사용하면 지급 대상이 A 프로필임을 확인하고 정확하게 상품을 지급할 수 있습니다.

이는 한 가지 예일 뿐입니다. 상품 구매 시각, 구매 사용자 정보 등 앱에 필요한 정보를 IapPayload에 담아 구매 영수증에 첨부할 수 있습니다. 앱의 상황에 맞게 활용하세요.

호출 예시

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

Unity

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

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

// 사용자가 결제 버튼을 누른 시점의 상품 정보로 요청 객체 생성
var request = new PrePurchase
{
    Country = "KR",
    Currency = "KRW",
    Language = "ko",
    Price = 1200.0m,
    ProductId = "com.game.item.gold_100",
    ProviderId = PrePurchaseProviderId.Steam,
    ServerId = "server01",
    RequestDate = DateTimeOffset.UtcNow
};

PaymentsCreatePrePurchaseResult result = await payments.CreatePrePurchaseAsync(request);

switch (result)
{
    case PaymentsCreatePrePurchaseResult.Success success:
        // 사전 저장 성공. 반환 데이터는 없습니다. Steam 결제 진행 단계로 넘어가세요.
        break;

    // 요청 값 문제 — 필수값과 형식 확인
    case PaymentsCreatePrePurchaseResult.PaymentBadRequest:
    case PaymentsCreatePrePurchaseResult.PaymentInvalidParameter:
        Debug.LogError("요청 파라미터를 확인하세요.");
        break;

    case PaymentsCreatePrePurchaseResult.UnknownOutcome unknownOutcome:
        Debug.LogWarning($"알 수 없는 결과: {unknownOutcome.Code}");
        break;

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

    // 안전망: 처리하지 않은 결과
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 별도 반환 데이터는 없습니다.

응답 예시

Unity

// Success 분기에서 별도 데이터 없이 Steam 결제 진행 단계로 이동합니다.

응답 상태

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

응답 케이스	설명	앱 클라이언트 대응
`Success`	사전 저장 성공	Steam 결제 진행 단계로 진행
`PaymentBadRequest`	결제 요청을 처리할 수 없습니다.	요청 값과 호출 조건을 점검
`PaymentInvalidParameter`	결제 요청 파라미터가 유효하지 않습니다.	요청 필드 값을 점검
`UnknownOutcome`	SDK가 알 수 없는 도메인별 결과입니다.	실패로 처리하고 결과 코드를 기록
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

3. Steam 결제 승인 콜백 수신

Steam은 사용자의 결제 승인 결과를 콜백으로 전달합니다. Hive Axyl Steam 결제 플러그인(com.com2usplatform.hiveaxyl.payments.addon.steam)의 ISteamMicrotransactionsPlugin으로 먼저 콜백 수신을 시작한 뒤 Steam 결제를 진행하세요. 사용자가 Steam 결제 창에서 결제를 마치면 MicroTxnAuthorizationResponse 이벤트로 주문번호와 승인 여부가 전달됩니다.

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Payments.Addon.Steam;

// 초기화 시 builder.AddSteamMicrotransactions()로 등록한 플러그인을 획득합니다.
if (!HiveCore.TryResolve<ISteamMicrotransactionsPlugin>(out var plugin))
{
    Debug.LogError("Steam 결제 플러그인이 등록되지 않았습니다.");
    return;
}

plugin.MicroTxnAuthorizationResponse += response =>
{
    if (response.Authorized)
    {
        // 사용자가 결제를 승인함 → 6. 결제 결과 데이터 저장 및 승인 확인 진행 (주문번호: response.OrderId)
    }
    else
    {
        // 사용자가 결제를 취소함 → 구매 흐름 종료 처리
    }
};

var startResult = await plugin.StartCallbackListenerAsync();
switch (startResult)
{
    case SteamMicrotransactionsServiceStartCallbackListenerResult.Success:
    case SteamMicrotransactionsServiceStartCallbackListenerResult.AlreadyStarted:
        // 콜백 수신 준비 완료 → 결제 세션 초기화(InitiatePurchaseAsync()) 진행
        break;

    default:
        // 수신 시작 실패(예: Steamworks 미초기화) — 결제 흐름을 시작하지 않습니다
        break;
}

4. Steam 결제 진행: 결제 세션 초기화

Steam Web API를 통해 결제를 진행하고 거래 ID를 발급받습니다.

InitiatePurchaseAsync

Steam 결제 시작을 구현하려면 Hive Axyl SDK가 제공하는 InitiatePurchaseAsync()를 호출하세요. Steam Web API를 통해 결제 세션을 초기화하고 거래 ID를 발급해 반환합니다. 이 메서드를 실행하면 Steam에서 사용자에게 Steam Overlay 결제 창을 표시합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	PurchaseInitRequest	Required	결제 세션 초기화 요청 데이터입니다.
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 멱등키·취소 토큰·요청 정책을 지정하며, 생략하면 기본값이 사용됩니다.

PurchaseInitRequest

필드명	타입	필수 여부	설명
`AppVersion`	string	Optional	앱 버전입니다.
`Country`	string	Required	`FetchSteamProductsAsync()` 응답에서 확인한 국가 코드입니다.
`Currency`	string	Required	`FetchSteamProductsAsync()` 응답에서 확인한 통화 코드입니다.
`IapPayload`	string	Optional	앱 데이터입니다.
`Language`	string	Required	언어 코드입니다.
`ProductId`	string	Required	스토어에 등록된 인앱 상품 ID입니다.
`ProviderId`	PurchaseInitRequestProviderId	Required	마켓 식별자입니다. Steam 결제 전용 요청이므로 `Steam`만 지정합니다.
`ServerId`	string	Optional	Hive 콘솔 앱 서버를 따라 `앱 정보 > 앱 서버`에서 앱 서버를 등록한 뒤 앱 서버 탭에서 확인하는 서버 ID입니다.
`StorePlayerId`	long	Required	Steam 64비트 SteamID입니다.

호출 예시

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

Unity

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

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

var request = new PurchaseInitRequest
{
    Country = "KR",
    Currency = "KRW",
    Language = "ko",
    ProductId = "com.game.product1",
    ProviderId = PurchaseInitRequestProviderId.Steam,
    StorePlayerId = 76561198000000000 // Steam 64비트 SteamID
};

PaymentsInitiatePurchaseResult result = await payments.InitiatePurchaseAsync(request);

switch (result)
{
    case PaymentsInitiatePurchaseResult.Success success:
        // 결제 세션 초기화 성공. 반환된 영수증과 거래 정보로 다음 단계 진행
        Debug.Log($"orderId: {success.Data.OrderId}, transId: {success.Data.StoreTransactionId}");
        break;

    case PaymentsInitiatePurchaseResult.PaymentBadRequest:
    case PaymentsInitiatePurchaseResult.PaymentInvalidParameter:
        // 요청 값과 필수 필드를 확인
        break;

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

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

응답 데이터

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

필드명	타입	필수 여부	설명
`Data.AxylReceipt`	string	Optional	서버가 발급한 AES 봉인 영수증입니다. 값을 변경하지 않고 보관했다가 `RecordStorePurchaseAsync()` 요청, 앱 서버에 전달하는 영수증 정보, 구매 완료 처리 요청에 그대로 사용합니다.
`Data.OrderId`	string	Required	Hive Axyl 내부 주문번호입니다. `RecordStorePurchaseAsync()` 요청에 그대로 전달합니다.
`Data.ProductId`	string	Required	스토어에 등록된 인앱 상품 ID입니다.
`Data.StoreTransactionId`	string	Required	Steam 거래 ID(Steam Web API의 transid)입니다. `RecordStorePurchaseAsync()` 요청에 그대로 전달합니다.
`Data.Meta`	string?	Optional	응답 메타 정보입니다.

응답 예시

Unity

// Success 분기에서 success.Data 예시
// success.Data.AxylReceipt = "Bg1THyMwfTZ/pn+SsPSEeykg4LaNHspLdrd8xQpvT/w="
// success.Data.OrderId = "2026010100001"
// success.Data.ProductId = "com.game.product1"
// success.Data.StoreTransactionId = "3390549843"

응답 상태

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

응답 케이스	설명	앱 클라이언트 대응
`Success`	결제 세션이 초기화되어 Hive Axyl 영수증, 주문번호 및 Steam 거래 ID가 반환되었습니다.	Steam 결제 창 표시 및 승인 대기 단계 진행
`PaymentBadRequest`	요청을 처리할 수 없습니다.	요청 값과 호출 조건을 확인
`PaymentInvalidParameter`	유효하지 않은 파라미터입니다.	요청 필드를 확인 후 수정
`UnknownOutcome`	SDK가 알 수 없는 도메인별 결과입니다.	실패로 처리하고 결과 코드를 기록
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

5. MicroTxnAuthorizationResponse 이벤트로 결제 승인 여부 수신

3단계에서 등록한 MicroTxnAuthorizationResponse 이벤트로 주문번호와 결제 승인 여부가 전달됩니다. Authorized가 true이면 다음 단계를 진행하고, false이면 구매 흐름을 종료하세요.

콜백 수신이 더 이상 필요 없으면 StopCallbackListenerAsync()를 호출해 해제합니다.

6. 결제 결과 데이터 저장 및 승인 확인

사용자가 Steam Overlay에서 결제를 승인한 직후 RecordStorePurchaseAsync()를 호출하세요. 이 단계는 구매 정보 기록의 결제 결과 저장 단계이면서, QueryTxn으로 승인을 확인하고 주문 상태를 0에서 1로 변경하는 Steam 표준 결제 흐름의 필수 단계입니다.

RecordStorePurchaseAsync

RecordStorePurchaseAsync()에 InitiatePurchaseAsync()가 반환한 AES 봉인 영수증과 주문 정보를 전달하세요. 이 메서드는 Steam 승인을 확인하고 결제 결과를 저장합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	PurchaseRequest	Required	결제 결과 저장 요청 데이터 객체입니다.
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 멱등키·취소 토큰·요청 정책을 지정하며, 생략하면 기본값이 사용됩니다.

PurchaseRequest

필드명	타입	필수 여부	설명
`AccountUuid`	string	Optional	로그인한 사용자의 `playerId`로 생성한 UUIDv5 값입니다. 결제 결과를 기록할 때 전달합니다. 결제 시작 단계에 전달한 경우 같은 값을 사용하세요. AccountUuid 생성을 참조하세요.
`AxylReceipt`	string	Required	결제 세션 초기화 응답의 `Data.AxylReceipt`를 값 그대로 전달합니다. 구매 복구로 되찾은 구매라면 그 응답의 `AxylReceipt`를 전달합니다. Steam 주문 번호만으로는 대신할 수 없습니다.
`Country`	string	Required	국가 코드(ISO 3166-1 두 자리)입니다. 예: `KR`
`Currency`	string	Optional	결제 통화(ISO 4217 세 자리)입니다. `Price`와 짝을 이뤄 서버가 기록한 값과 대조하는 데 사용합니다. 둘 중 하나만 보내면 통화는 대조하지 않고 금액만 대조합니다.
`IapPayload`	string	Optional	개발자가 마켓 결제 시 첨부한 페이로드(JSON 문자열). 앱 서버 검증과 구매 완료 콜백에 그대로 전달됩니다.
`Language`	string	Required	언어 코드(ISO 639-1 두 자리)입니다. 예: `ko`
`OrderId`	string	Optional	Steam 구매 초기화 응답의 Hive Axyl 내부 주문 번호입니다.
`Price`	decimal	Optional	결제 금액입니다. 통화에 따라 소수점이 포함될 수 있습니다. 보내면 서버가 기록한 금액과 대조하고, 생략하면 대조하지 않습니다. Steam 결제는 금액이 다르면 요청을 거절합니다. 결제 내역에 남는 금액은 서버가 보관한 주문 정보의 값입니다.
`ProductId`	string	Required	마켓에 등록한 인앱 상품 ID입니다. Steam 결제는 서버에 저장된 주문 정보를 기준으로 처리하므로 이 값을 대조에 사용하지 않습니다.
`ProjectInfo`	string	Optional	앱별 자유 형식 JSON 문자열입니다. 값은 저장만 하며 앱 서버로 전달하지 않습니다. 앱 서버로 전달할 값은 `IapPayload`에 설정하세요.
`ProviderId`	PurchaseRequestProviderId	Required	Steam 결제 결과 저장 전용 요청이므로 `Steam`을 지정합니다.
`Quantity`	int	Optional	구매 수량
`RequestDate`	DateTimeOffset	Optional	클라이언트 요청 시각(UTC)입니다. 생략하면 서버의 현재 시각을 사용합니다.
`RequestType`	int	Optional	요청 유형입니다. `1`: 신규 구매, `2`: 구매 복원
`ServerId`	string	Optional	Hive 콘솔 앱 서버를 따라 등록한 앱 서버 ID입니다.
`StoreTransactionId`	string	Optional	Steam 스토어 거래 ID입니다.

호출 예시

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

Unity

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

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

// InitiatePurchaseAsync() 성공 응답에서 받은 값을 사용해 승인 확인 요청을 생성합니다.
var request = new PurchaseRequest
{
    AxylReceipt = axylReceipt,
    OrderId = orderId,
    ProviderId = PurchaseRequestProviderId.Steam,
    ProductId = "com.game.item.gold_100",
    Price = 1200.0m,
    Currency = "KRW",
    Country = "KR",
    Language = "ko",
    Quantity = 1,
    StoreTransactionId = storeTransactionId,
    RequestType = 1, // 1: 신규 구매
    RequestDate = DateTimeOffset.UtcNow,
    ServerId = "server01"
};

PaymentsRecordStorePurchaseResult result = await payments.RecordStorePurchaseAsync(request);

switch (result)
{
    case PaymentsRecordStorePurchaseResult.Success success:
        // 승인 확인과 저장에 성공했습니다. success.Data.Meta를 확인할 수 있습니다.
        break;

    // 요청 값 또는 결제 상태 문제
    case PaymentsRecordStorePurchaseResult.PaymentBadRequest:
    case PaymentsRecordStorePurchaseResult.PaymentInvalidParameter:
    case PaymentsRecordStorePurchaseResult.PaymentResourceNotFound:
    case PaymentsRecordStorePurchaseResult.PaymentUnauthorized:
    case PaymentsRecordStorePurchaseResult.VerifyError:
        Debug.LogError("요청 값과 결제 상태를 확인하세요.");
        break;

    case PaymentsRecordStorePurchaseResult.UnknownOutcome unknownOutcome:
        Debug.LogWarning($"알 수 없는 결과: {unknownOutcome.Code}");
        break;

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

    // 안전망: 처리하지 않은 결과
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

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

필드명	타입	필수 여부	설명
`Data.Meta`	string	Optional	응답 메타 정보

응답 예시

Unity

// Success 분기에서 success.Data.Meta를 확인할 수 있습니다.

응답 상태

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

응답 케이스	설명	앱 클라이언트 대응
`Success`	결제 결과 저장 성공	앱 서버에 영수증 정보를 전달해 영수증 검증 단계로 진행
`PaymentBadRequest`	결제 요청을 처리할 수 없습니다.	요청 값과 호출 조건을 점검
`PaymentInvalidParameter`	결제 요청 파라미터가 유효하지 않습니다.	`AxylReceipt` 등 요청 필드 값을 점검
`PaymentResourceNotFound`	저장할 결제 정보를 찾을 수 없습니다.	영수증과 거래 정보를 점검
`PaymentUnauthorized`	결제 요청 권한이 없습니다.	앱과 인증 상태를 점검
`VerifyError`	결제 검증 중 오류가 발생했습니다.	영수증과 마켓 결제 상태를 점검
`UnknownOutcome`	SDK가 알 수 없는 도메인별 결과입니다.	실패로 처리하고 결과 코드를 기록
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

다음 단계

4단계. 영수증 검증을 진행합니다.