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	必填	支付商品 ID
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 及以上。

本地证书链验证

服务器以 Apple Root CA G3 为基准验证 (ES256) JWS 内置的 x5c 证书链，无需向 Apple 服务器进行额外调用或密钥文件 (.p8)。Sandbox / Xcode 支付会以测试模式保存，不计入销售额。

退款检测 (Webhook)

注册 App Store Server Notifications(Version 2) 后，将自动接收退款 (REFUND) 事件。注册 URL 为 https://service-api.playnanoo.com/webhook/apple/{gameId}，详细内容请参考控制台的 API 及平台设置 > iOS。