결제 완료 정보 조회 (미지급 주문 조회)

PG 결제는 외부 브라우저에서 완료되므로, 사용자가 앱으로 돌아온 뒤 결제는 완료되었으나 아직 상품이 지급되지 않은 주문, 즉 미지급 주문을 조회해 결제 결과를 가져옵니다. 조회 결과의 AxylReceipt는 서버가 발급한 봉인 영수증입니다. 앱 클라이언트가 이 값과 주문 정보를 앱 서버에 전달하면 앱 서버가 이 값을 영수증 검증 요청에 그대로 넣습니다.

RestorePurchasesAsync

미지급 주문을 조회해 결제 결과를 가져오려면 Hive Axyl SDK가 제공하는 RestorePurchasesAsync()를 호출하세요. 결제는 완료되었지만 상품 미지급 상태인 이전 구매 목록을 반환합니다.

호출 파라미터

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

PurchaseRestoreRequest

필드명	타입	필수 여부	설명
ProviderId	PurchaseRestoreRequestProviderId	Required	마켓 식별자입니다. PG 미지급 주문 조회 전용 요청이므로 Pg만 지정합니다.
AppVersion	string	Optional	앱 버전입니다.
Country	string	Required	국가 코드(ISO 3166-1 두 자리)입니다. 예: KR
Language	string	Required	언어 코드(ISO 639-1 두 자리)입니다. 예: ko
ServerId	string	Optional	Hive 콘솔 앱 서버를 따라 앱 정보 > 앱 서버에서 앱 서버를 등록한 뒤 앱 서버 탭에서 확인하는 서버 ID입니다. 지정하면 해당 서버의 주문만 반환하고, 생략하면 모든 주문을 반환합니다.

호출 예시

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

Unity

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

// payments: 초기화 시 등록된 IPaymentsService. 모듈 설치, 초기화, 로그인 참고.
IPaymentsService payments = HiveCore.Resolve<IPaymentsService>();

var request = new PurchaseRestoreRequest
{
    ProviderId = PurchaseRestoreRequestProviderId.Pg,
    Country = "KR",
    Language = "ko",
    ServerId = "server01"
};

PaymentsRestorePurchasesResult result = await payments.RestorePurchasesAsync(request);

switch (result)
{
    case PaymentsRestorePurchasesResult.Success success:
        // 복구 가능한 구매 목록 처리
        if (success.Data.Restores is { } restores)
        {
            foreach (var restore in restores)
            {
                Debug.Log($"orderId: {restore.OrderId}, productId: {restore.ProductId}");
            }
        }
        break;

    case PaymentsRestorePurchasesResult.PaymentBadRequest:
        // 요청을 처리할 수 없습니다. 요청 값과 호출 조건 확인
        break;

    case PaymentsRestorePurchasesResult.PaymentInvalidParameter:
        // 유효하지 않은 파라미터입니다. 요청 값 확인
        break;

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

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

응답 데이터

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

필드명	타입	필수 여부	설명
Data.Restores	IReadOnlyList<RestorePurchase>?	Optional	결제는 완료되었지만 상품이 지급되지 않은 구매 목록입니다.
Data.Meta	string?	Optional	응답 메타 정보입니다.

RestorePurchase

필드명	타입	필수 여부	설명
Currency	string	Optional	통화 코드입니다.
GameServerPriceVerifyKey	string	Optional	앱 서버 결제 금액 검증 키입니다.
IapPayload	string	Optional	앱 서버로 전달할 추가 페이로드입니다.
OrderId	string	Optional	주문 ID입니다.
PaidDateTime	string	Optional	결제 완료 시각입니다(yyyy-MM-dd HH:mm:ss).
PaidDateTimeMs	long	Optional	결제 완료 시각입니다(Unix epoch 밀리초 단위).
Price	decimal	Optional	결제 금액입니다.
ProductId	string	Optional	상품 ID(market_pid)입니다.
ProviderId	RestorePurchaseProviderId	Required	결제 수단 식별자입니다. 이 응답에서는 Pg가 반환됩니다.
PurchaseDateTime	long	Optional	구매 일시입니다(Unix epoch 밀리초 단위).
Quantity	int	Optional	구매 수량입니다.
StartedDateTime	string	Optional	결제 시작 시각입니다(yyyy-MM-dd HH:mm:ss).
StartedDateTimeMs	long	Optional	결제 시작 시각입니다(Unix epoch 밀리초 단위).
StoreTransactionId	string	Optional	PG 스토어 거래 ID입니다. 주문 ID와 다를 수 있습니다.
AxylReceipt	string	Optional	서버가 발급한 봉인 영수증입니다. 앱 서버에 전달하는 영수증 검증 요청 값의 axylReceipt와 구매 완료 처리 요청의 AxylReceipt로 그대로 사용합니다.

응답 예시

Unity

// Success 분기에서 success.Data 예시
// success.Data.Restores[0].OrderId = "1000000012345"
// success.Data.Restores[0].ProductId = "com.example.gem.100"
// success.Data.Restores[0].ProviderId = RestorePurchaseProviderId.Pg
// success.Data.Restores[0].Price = 9900.0
// success.Data.Restores[0].Currency = "KRW"
// success.Data.Restores[0].Quantity = 1
// success.Data.Restores[0].PurchaseDateTime = 1717200000000
// success.Data.Restores[0].AxylReceipt = "Bg1THyMwfTZ/pn+SsPSEeykg4LaNHspLdrd8xQpvT/w="

응답 상태

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

응답 케이스	설명	앱 클라이언트 대응
Success	복구 가능한 구매 목록이 반환되었습니다.	각 구매 건의 AxylReceipt를 앱 서버에 전달해 영수증 검증 진행 후 상품 지급
PaymentBadRequest	요청을 처리할 수 없습니다.	요청 값과 호출 조건을 점검
PaymentInvalidParameter	유효하지 않은 파라미터입니다(예: 필수값 누락).	필수 필드 값 확인 후 수정
PaymentResourceNotFound	결제 정보를 찾을 수 없습니다.	영수증·주문 번호·결제 상태를 확인
UnknownOutcome	SDK가 알 수 없는 도메인별 결과입니다.	실패로 처리하고 결과 코드를 기록
Failure	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

영수증 검증 요청 값 전달

앱 서버가 영수증 검증을 요청하려면 앱 클라이언트가 조회한 미지급 주문 정보를 앱 서버에 전달해야 합니다. 미지급 주문마다 소모성 상품 영수증 검증 요청에 필요한 아래 값을 모아 앱에서 구현한 앱 서버 API로 전달하세요. 앱 서버는 각 값을 영수증 검증 요청에서 이름이 같은 필드에 넣습니다.

• axylReceipt: RestorePurchase.AxylReceipt. Hive Axyl 서버가 발급한 봉인 영수증이므로 값을 가공하지 않은 원문
• productId: RestorePurchase.ProductId
• accountUuid: AccountUuid 생성에서 만든 값
• requestType: 결제를 마치고 돌아와 조회한 주문은 신규 구매이므로 1, 구매 복구에서 조회한 주문은 2
• 선택: RestorePurchase의 Price, Currency, IapPayload를 담은 price, currency, iapPayload
• 선택: 미지급 주문 조회에 사용한 ServerId를 담은 serverId

다음 단계

앱 서버에서 Hive Axyl Server API로 영수증을 검증합니다.