5단계. 상품 지급

영수증 검증이 완료되면 앱 서버가 사용자에게 상품을 지급하고, 앱 클라이언트가 PG 결제의 구매 완료 처리를 수행한 뒤 지급 결과를 Hive Axyl 서버에 기록합니다. 앱 클라이언트가 이 단계에서 사용하는 hiveAxylTransactionId는 앱 서버가 영수증 검증 응답에서 받아 전달한 값입니다.

1. 상품 지급

앱 서버가 영수증 검증 결과를 확인한 뒤 결제한 사용자에게 상품을 지급합니다. 상품 지급은 앱에서 구현하며, 지급 방식은 앱별로 다를 수 있습니다.

구매 완료 처리는 앱 서버의 상품 지급이 끝난 뒤에 진행하세요. 미지급 주문 조회는 마감되지 않은 주문만 찾으므로, 지급보다 먼저 구매 완료 처리로 주문을 마감하면 지급 도중 앱이 중단됐을 때 그 주문을 다시 찾을 수 없습니다.

2. 구매 완료 처리

PG 결제에서 최종 구매 완료 처리를 수행합니다. 결제 상태를 완료로 변경하고 관련 데이터를 업데이트합니다.

구매 완료 처리는 해당 주문을 소비 상태로 만듭니다. 이 단계를 건너뛰면 결제가 끝난 주문이 미소비 상태로 남아 구매 복구의 미지급 주문 조회 결과에 계속 포함됩니다.

FinalizePurchaseAsync

구매 완료 처리를 구현하려면 Hive Axyl SDK가 제공하는 FinalizePurchaseAsync()를 호출하세요. PG 결제의 최종 구매 완료 처리를 수행하여 결제 상태를 완료로 변경하고 관련 데이터를 갱신합니다.

호출 파라미터

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

PurchaseFinalizeRequest

필드명	타입	필수 여부	설명
`AxylReceipt`	string	Required	결제 완료 정보 조회가 반환한 미지급 주문의 `AxylReceipt`를 값 그대로 전달합니다. 앱 서버에 영수증 검증을 요청할 때 전달한 봉인 영수증과 같은 값입니다. 서버가 이 값을 복호화해 완료 처리할 주문을 찾으므로, 값을 가공하면 요청이 거절됩니다.
`ProviderId`	PurchaseFinalizeRequestProviderId	Required	마켓 식별자입니다. PG 구매 완료 처리 전용 요청이므로 `Pg`만 지정합니다.

호출 예시

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

Unity

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

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

var request = new PurchaseFinalizeRequest
{
    AxylReceipt = axylReceipt, // 미지급 주문 조회가 반환한 AxylReceipt. 앱 서버에 검증을 요청할 때 전달한 값과 같은 값
    ProviderId = PurchaseFinalizeRequestProviderId.Pg
};

PaymentsFinalizePurchaseResult result = await payments.FinalizePurchaseAsync(request);

switch (result)
{
    case PaymentsFinalizePurchaseResult.Success success:
        // 구매 완료 처리 성공. PG 주문 번호와 Axyl 거래 번호 확인
        Debug.Log($"orderId: {success.Data.OrderId}, storeTransactionId: {success.Data.StoreTransactionId}");
        break;

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

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

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

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

응답 데이터

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

필드명	타입	필수 여부	설명
`Data.OrderId`	string	Optional	PG 주문 번호입니다. `H`로 시작하는 문자열입니다.
`Data.StoreTransactionId`	string	Optional	Hive Axyl 거래 번호입니다.
`Data.Meta`	string?	Optional	응답 메타 정보입니다.

응답 예시

Unity

// Success 분기에서 success.Data 예시
// success.Data.OrderId = "H517815844374710159"
// success.Data.StoreTransactionId = "3390549843"

응답 상태

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

응답 케이스	설명	앱 클라이언트 대응
`Success`	결제 상태가 완료로 변경되었습니다.	주문번호·거래 ID 확인 후 다음 단계 진행
`PaymentBadRequest`	요청을 처리할 수 없습니다.	요청 값과 호출 조건을 점검
`PaymentInvalidParameter`	유효하지 않은 파라미터입니다(예: 필수값 누락).	필수 필드 값 확인 후 수정
`PaymentResourceNotFound`	결제 정보를 찾을 수 없습니다.	영수증·주문 번호·결제 상태를 확인
`UnknownOutcome`	SDK가 알 수 없는 도메인별 결과입니다.	실패로 처리하고 결과 코드를 기록
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

3. 상품 지급 결과 저장

앱 서버에서 상품 지급을 완료한 후, 성공 또는 취소 등 지급 결과를 Hive Axyl 서버에 기록합니다.

ItemResultAsync

소모성 상품 지급 결과 저장을 구현하려면 Hive Axyl SDK가 제공하는 ItemResultAsync()를 호출하세요. 상품 지급이 완료된 뒤 그 결과를 Hive Axyl 서버에 기록합니다. 이 메서드는 결제를 확정하거나 상품 지급 여부를 결정하지 않습니다.

호출 시점: 앱 서버의 상품 지급 완료 후
AxylTransactionId 값: 앱 서버가 영수증 검증 응답에서 받아 전달한 hiveAxylTransactionId
취소 처리: 지급 실패 시 Status에 취소 상태값 설정

호출 파라미터

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

ItemResultBody

필드명	타입	필수 여부	설명
`AxylTransactionId`	string	Required	Hive Axyl 결제 트랜잭션 ID (접두사로 마켓 구분). 앱 서버가 영수증 검증 응답에서 받아 전달한 `hiveAxylTransactionId` 값을 사용합니다.
`Status`	int	Required	지급 결과 상태입니다. `1`: 지급 성공, `2`: 취소 후 상품 회수 없음, `3`: 취소 후 상품 회수이며, 그 외 값은 유효하지 않습니다.
`Assets`	IReadOnlyList<ItemResultAsset>	Optional	실제 지급된 상품 목록입니다. 기록할 항목이 없으면 이 필드를 생략하세요.
`ProjectPayloadInfo`	string	Optional	앱별 자유 형식 JSON 데이터 (JSON 문자열)

ItemResultAsset

필드명	타입	필수 여부	설명
`AssetId`	string	Optional	앱 내 상품 고유 ID
`AssetName`	string	Optional	앱 내 상품 이름
`Quantity`	int	Optional	지급 수량입니다. 지정하는 경우 1 이상이어야 합니다.

호출 예시

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

Unity

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

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

// 상품 지급 완료 후, 지급 결과로 요청 객체 생성
var request = new ItemResultBody
{
    AxylTransactionId = axylTransactionId, // 앱 서버가 전달한 영수증 검증 응답의 hiveAxylTransactionId
    Status = 1, // 1: 지급 성공
    Assets = new[]
    {
        new ItemResultAsset { AssetId = "item_gold_100", AssetName = "골드 100개", Quantity = 1 }
    },
    ProjectPayloadInfo = "{\"serverId\":\"server01\"}" // (선택) 앱별 자유 형식 JSON 데이터
};

PaymentsItemResultResult result = await payments.ItemResultAsync(request);

switch (result)
{
    case PaymentsItemResultResult.Success success:
        // 지급 결과 기록 성공. success.Data.Meta를 확인할 수 있습니다.
        break;

    // 요청 값 문제 — 필수값·수량·상태값 확인
    case PaymentsItemResultResult.PaymentInvalidParameter:
    case PaymentsItemResultResult.PaymentBadRequest:
        Debug.LogError("요청 파라미터를 확인하세요.");
        break;

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

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

응답 데이터

성공 시 PaymentsItemResultResult.Success의 Data(SuccessResponseData)에 응답 메타 정보가 담깁니다.

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

응답 예시

Unity

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

응답 상태

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

응답 케이스	설명	앱 클라이언트 대응
`Success`	지급 결과 기록 성공	다음 결제 처리 진행
`InvalidQuantity`	지급 수량이 유효하지 않습니다.	지급 수량을 확인
`InvalidStatus`	지급 결과 상태 값이 유효하지 않습니다.	`Status` 값을 확인
`PaymentBadRequest`	요청을 처리할 수 없습니다.	요청 값과 호출 조건을 점검
`PaymentInvalidParameter`	유효하지 않은 파라미터인 경우 (예: `AxylTransactionId` 누락)	필수 파라미터 설정 확인
`PaymentResourceNotFound`	결제 정보를 찾을 수 없습니다.	영수증·주문 번호·결제 상태를 확인
`UnknownOutcome`	SDK가 알 수 없는 도메인별 결과입니다.	실패로 처리하고 결과 코드를 기록
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

더 알아보기

결제 과정에서 네트워크 오류 등으로 상품을 지급하지 못한 경우 구매 복구를 구현하세요.