iOS 영수증 검증 (StoreKit 2)

StoreKit 2 의 서명된 거래(Signed Transaction, JWS)를 검증하는 API입니다.

URL 확인

이 API는 service-api.playnanoo.com 도메인을 사용합니다.

StoreKit 2 (JWS) 방식

이 API는 StoreKit 2 (iOS 15.0 이상) 의 서명된 거래(JWS)를 검증합니다. StoreKit 1 의 Base64 영수증을 사용하는 경우 iOS 영수증 검증 을 참고하세요. Unreal SDK에는 전용 헬퍼가 없으므로 아래와 같이 raw HTTP 로 호출합니다.

API 정보

URL: https://service-api.playnanoo.com/iap/v20260401/ios
Method: PUT
인증 필요: 예

요청 파라미터

파라미터	타입	필수	설명
jws_transaction	string	필수	서명된 거래 정보 (JWS)
product_id	string	필수	결제 상품 아이디
duplicate_allow	string	선택	영수증 중복 검증 허용 여부 (Y/N)

currency / price 파라미터 없음

레거시 v20221001 과 달리 currency, price 를 전달하지 않습니다. 통화·금액은 서버가 JWS payload 에서 직접 추출합니다.

응답 데이터

필드	타입	설명
UserID	string	사용자 ID
PackageName	string	패키지 이름
OrderID	string	주문 ID (transactionId)
ProductID	string	상품 ID
Quantity	string	수량
Currency	string	통화 코드
Price	string	가격
PurchaseState	string	검증 결과 (`purchase` / `wait` / `cancel`)

코드 예제

void UMyGame::ValidateIOSIAPJWS(const FString& JwsTransaction, const FString& ProductId, bool bDuplicateAllow)
{
    // 플레이어 정보가 포함된 요청 바디 생성
    TSharedPtr<FJsonObject> Body = FPlayNANOOHelper::CreateRequestBody();
    Body->SetStringField(TEXT("jws_transaction"), JwsTransaction);
    Body->SetStringField(TEXT("product_id"), ProductId);
    Body->SetStringField(TEXT("duplicate_allow"), bDuplicateAllow ? TEXT("Y") : TEXT("N"));

    // JSON 문자열 변환
    FString JsonBody = FPlayNANOOHelper::ToJsonString(Body);

    // HTTP 요청
    TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest();
    Request->SetURL(TEXT("https://service-api.playnanoo.com/iap/v20260401/ios"));
    Request->SetVerb(TEXT("PUT"));
    FPlayNANOOHelper::SetCommonHeaders(Request, true);  // 인증 토큰 포함
    Request->SetContentAsString(JsonBody);

    Request->OnProcessRequestComplete().BindLambda(
        [](FHttpRequestPtr Req, FHttpResponsePtr Res, bool bSuccess)
    {
        if (bSuccess && Res.IsValid())
        {
            TSharedPtr<FJsonObject> JsonObject;
            TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(Res->GetContentAsString());

            if (FJsonSerializer::Deserialize(Reader, JsonObject))
            {
                FString UserID = JsonObject->GetStringField(TEXT("UserID"));
                FString OrderID = JsonObject->GetStringField(TEXT("OrderID"));
                FString ProductID = JsonObject->GetStringField(TEXT("ProductID"));
                FString ValidatedPrice = JsonObject->GetStringField(TEXT("Price"));
                FString ValidatedCurrency = JsonObject->GetStringField(TEXT("Currency"));
                FString PurchaseState = JsonObject->GetStringField(TEXT("PurchaseState"));

                UE_LOG(LogTemp, Log, TEXT("IAP 검증 성공 - 주문ID: %s, 상품ID: %s, 가격: %s %s, 상태: %s"),
                    *OrderID, *ProductID, *ValidatedPrice, *ValidatedCurrency, *PurchaseState);
            }
        }
    });

    Request->ProcessRequest();
}

JWS 획득

jws_transaction 은 StoreKit 2 의 서명된 거래(Signed Transaction) 문자열입니다. 획득 방법은 클라이언트의 StoreKit 2 연동 방식에 따릅니다. StoreKit 2 는 iOS 15.0 이상 이 필요합니다.

로컬 인증서 체인 검증

서버는 JWS 내장 x5c 인증서 체인을 Apple Root CA G3 기준으로 검증(ES256)하며, Apple 서버로의 추가 호출이나 키파일(.p8)이 필요하지 않습니다. Sandbox / Xcode 결제는 테스트 모드로 저장되어 매출에 집계되지 않습니다.

환불 감지 (Webhook)

App Store Server Notifications(Version 2)를 등록하면 환불(REFUND) 이벤트를 자동으로 수신합니다. 등록 URL은 https://service-api.playnanoo.com/webhook/apple/{gameId} 이며, 자세한 내용은 콘솔의 API 및 플랫폼 설정 > iOS 를 참고하세요.

iOS 영수증 검증 (StoreKit 2)

API 정보​

요청 파라미터​

응답 데이터​

코드 예제​

API 정보

요청 파라미터

응답 데이터

코드 예제