결제 확정과 지급 결과 기록

앱 서버가 소모성 상품의 영수증을 검증한 뒤에는 앱 클라이언트가 결제 확정 요청을 보내고 상품 지급 결과를 기록합니다. RequestPurchaseAsync()는 결제 확정 요청을 전송하며, ItemResultAsync()는 앱 또는 앱 서버가 처리한 상품 지급 결과를 기록합니다. 두 메서드에 필요한 값 가운데 영수증 검증 응답에 담긴 값은 앱 서버가 앱 클라이언트에 전달합니다.

1. 결제 확정 요청

Apple App Store와 Google Play 결제는 앱 서버의 영수증 검증이 끝난 뒤 RequestPurchaseAsync()를 호출해 결제 확정 요청을 전송합니다. 이 요청은 소모성 상품에만 사용합니다. 상품 지급과 이 요청의 호출 순서는 앱이 결정하지만, 상품 유실을 막으려면 상품을 먼저 지급한 뒤 결제 확정 요청을 전송하세요. 결제 확정 요청을 보낸 뒤에는 Apple은 거래 완료 처리를, Google은 소모성 상품 거래 완료 처리를 진행하고, 이어서 2. 상품 지급 결과 기록을 진행하세요. 상품 지급 결과 기록은 거래 완료 처리의 선행 조건이 아니므로, 기록이 실패해도 거래 완료 처리를 미루지 마세요.

구독 상품은 RequestPurchaseAsync() 대신 Apple 구독 완료 처리와 Google 구독 완료 처리로 구독을 확정합니다. PG 결제의 처리 흐름은 PG 상품 지급을 참조하세요. Steam 결제는 RequestPurchaseAsync() 대신 Steam 구매 완료 처리를 사용합니다.

RequestPurchaseAsync

호출 파라미터

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

PurchasePostRequest

필드명	타입	필수 여부	설명
AxylReceipt	string	Required	확정할 구매 건의 영수증입니다. Apple은 StoreKit 2 트랜잭션 JWS, Google은 구매 토큰(purchaseToken)을 전달합니다.
FinalizationMsg	string	Optional	Apple 또는 Google 결제의 확정 메시지입니다.
ProductId	string	Optional	Google 결제의 상품 ID입니다. AxylReceipt에 구매 토큰(purchaseToken) 문자열을 전달할 때는 토큰에 상품 정보가 없으므로 이 값을 반드시 전달하세요. 전달하지 않으면 서버가 요청을 거절합니다. purchase_data와 signature를 담은 예전 형식을 전달할 때는 영수증에서 상품 ID를 읽으므로 생략해도 됩니다.
ProviderId	PurchasePostRequestProviderId	Required	마켓·결제 수단 식별자입니다.
StoreTransactionId	string	Optional	Apple 결제의 스토어 거래 ID입니다. Apple에서는 StoreKit 2 재검증 키이므로 반드시 전달합니다.

PurchasePostRequest에는 AccountUuid 필드가 없습니다. 따라서 RequestPurchaseAsync()에는 AccountUuid를 전달하지 않습니다.

호출 예시

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

Unity

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

IPaymentsService payments = HiveCore.Resolve<IPaymentsService>();

var request = new PurchasePostRequest
{
    AxylReceipt = receipt,
    ProductId = "com.game.item.gold_100",
    ProviderId = PurchasePostRequestProviderId.Google
};

PaymentsRequestPurchaseResult result = await payments.RequestPurchaseAsync(request);

switch (result)
{
    case PaymentsRequestPurchaseResult.Success success:
        Debug.Log($"결제 확정 요청 완료: {success.Data.Meta}");
        break;

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

    case PaymentsRequestPurchaseResult.VerifyDuplicated:
        Debug.LogError("이미 처리한 결제인지 확인하세요.");
        break;

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

    case PaymentsRequestPurchaseResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

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

응답 데이터

성공 시 PaymentsRequestPurchaseResult.Success의 Data에 응답 메타 정보가 담깁니다.

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

응답 상태

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

2. 상품 지급 결과 기록

상품을 지급한 뒤 ItemResultAsync()로 지급 결과를 기록하세요. 이 메서드는 지급 결과를 남기는 용도입니다. 결제를 확정하거나 상품 지급 여부를 결정하지 않습니다. 요청의 AxylTransactionId에는 앱 서버가 영수증 검증 응답에서 받아 앱 클라이언트에 전달한 hiveAxylTransactionId를 넣으세요.

상품 지급 복구와 재시도는 앱 또는 앱 서버에서 처리합니다. 결제 제공자별 ItemResultAsync() 호출 방법은 Apple 상품 지급, Google 상품 지급, Steam 상품 지급, PG 상품 지급을 참조하세요.