PG 付款

以下說明 PG 付款功能與收據處理方式。

在套用PG 付款前，請先確認PG 付款政策，並依 PG 付款 Hive Console 指南中的前置作業，於 Hive Console 註冊必要資訊。

PG payment features¶

PG 付款的主要功能如下：

PG 付款以 IAP v4 與 PG Payment API 為基礎運作，並透過付款代行機構（PG）提供的 Web 瀏覽器非同步處理。
已完成付款的訂單，必須透過 transactionFinish(marketPid) API 完成商品付款完成處理。
若要再次購買已付款但尚未完成付款完成處理的商品，付款將不會進行。請先完成先前商品的付款完成處理。
在尚有未完成付款訂單時（例如同時開啟多個付款視窗）嘗試加購其他商品時，僅第一筆付款會完成，其餘購買即使已付款也會自動取消。
即使已送出付款完成處理請求，遊戲伺服器仍可依策略取消該筆付款。

PC PG 付款¶

Info

PC PG 付款於 Hive SDK 25.1.0 以上版本支援。

在 PC 環境進行 PG 付款時，會以新視窗顯示如下付款請求畫面。

行動端 PG 付款¶

Info

行動端 PG 付款於 Hive SDK 26.3.2 以上版本支援。

在行動環境進行 PG 付款時，會透過 App 內 WebView 顯示付款請求畫面。

Warning

在行動環境進行 PG 付款時，必須先呼叫 setMarketSelection API 將市場切換為 Hive Store。若未切換即發起購買，將以原市場（Google Play、App Store 等）進行付款。詳細內容請參考市場切換呼叫建議時機。

Tip

PG 付款完成後，若要切回原市場（App Store、Google Play 等），請再次呼叫 setMarketSelection API。例如 iOS 可呼叫 setMarketSelection(IAPV4Type.appStore)。

事前準備事項¶

若要使用行動端 PG 付款，專案中必須**新增 HiveStore 模組**。請依各 SDK 的開發引擎與目標 OS 參考以下說明。

SDK Native Android¶

在模組層級的 build.gradle 檔案中加入 HiveStore 市場函式庫。

implementation "com.com2us.android.hive:hive-iapv4-market-hivestore" // Hive Store(PG)

Note

詳細請參考 Hive SDK Android Billing 設定。

SDK Native iOS¶

在專案目錄的 Podfile 加入 App 內付款框架與 PG(HiveStore) 框架。

pod 'HiveIAPV4', $HIVE_SDK_VERSION
pod 'HiveIAPV4HiveStore', $HIVE_SDK_VERSION // Hive Store(PG)

Note

詳細請參考 Hive SDK iOS Billing 設定。

Unity¶

在 Unity 編輯器點擊 Hive > ExternalDependency。
在 Market Settings 選擇 Hive Store。

Note

詳細請參考 Hive SDK Unity Billing 設定。

Unreal¶

在 Unreal 編輯器選單點擊 Edit > Project Settings。
在左側面板點擊 Hive SDK > Dependency - Android / Hive SDK > Dependency - iOS。
在 Market 中選擇 Hive Store。

Note

詳細請參考 Hive SDK Unreal Engine Billing 設定。

行動端 PG 付款政策¶

行動端 PG 付款的支援範圍受各平台政策限制。

Platform	Supported	Note
iOS	US storefront only	支援狀態可能因 Apple App Review Guidelines 更新而變更
Android	Not supported	-

iOS 實作注意事項¶

在 iOS 上，依據 Apple 的 App Review Guidelines (Guideline 3.1.1, 3.1.1(a), 3.1.3)，PG 付款僅支援 US storefront。Apple 於 2025 年 5 月因應美國法院判決更新指南，允許在 US storefront 中顯示導引用戶至 IAP 以外付款方式的按鈕、外部連結與 CTA，且無需額外 Entitlement。

在美國以外 storefront 中，若於 App 內顯示導向 IAP 以外付款方式的按鈕或連結，將在 Apple 審核時被拒。
建議依使用者 storefront 地區分流控制 PG 付款入口顯示。

Warning

Apple 的 App Review Guidelines 可能變更。送審前請務必確認最新指南。

不得僅設定第三方付款方式

依 Apple 政策，App 必須包含 App Store IAP 作為預設付款方式。請勿在 Hive Console 僅設定 Hive Store(PG) 市場。 僅提供第三方付款方式的 App 可能在 Apple 審核中遭拒，或被 App Store 下架。請務必與 App Store 市場一併設定。

行動端 PG 付款串接流程¶

在行動環境串接 PG 付款的流程如下。

付款與收據處理流程¶

PC 與行動端 PG 付款的收據處理流程相同，不同點是行動端在發起購買前需額外先將 market 切換為 Hive Store。

（僅行動端） 呼叫 IAPV4.setMarketSelection(IAPV4Type.hiveStore) 將 market 切換為 Hive Store
呼叫 IAPV4.purchase(marketPid, iapPayload, onIAPV4PurchaseCB) 發起購買

Warning

若已在 Hive Console Billing > Payment Environment Settings > PG Settings > Optional Feature Settings 註冊付款完成資訊 URL，請先刪除此 URL。
商品購買成功後，透過 onIAPV4PurchaseCB callback 接收收據資訊（bypassInfo）
遊戲客戶端將此收據資訊傳送至遊戲伺服器
遊戲伺服器呼叫 Receipt Verification API 驗證此收據資訊
驗證完成後，呼叫 IAPV4.transactionFinish 完成商品發放

若在上述第 3 步未透過 onIAPV4PurchaseCB 收到代表購買成功的收據資訊，請呼叫 IAPV4.restore 重新請求未發放項目的收據資訊，接著依第 4-6 步完成收據驗證與商品發放。

Note

收據處理流程與驗證方式詳情，請參閱 Receipt Verification。

多數量購買¶

Hive PG 付款 支持多數量購買。通過在請求購買時指定數量，您可以在一次付款中購買多個相同的應用內產品。

Hive SDK 调用 hive.IAPV4.purchase(marketPid, iapPayload, quantity, onIAPV4PurchaseCB)，并使用 quantity params，允许您指定数量。

Note

多數量購買僅支持可重複購買的消耗性應用內產品。請小心不要重複購買一次性產品。

請求多數量購買的範例代碼如下。

Unity虛幻引擎C++KotlinJavaSwiftObjective-C

API 參考: [hive .IAPV4.purchase](http://developers.withhive.com/HTML/v4_api_reference/Unity3D/group___i_a_p_v4.html#ga4f5a16cebe1b2b1fab22126faacafbec)

```cs
using hive;    
        String marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
        String iapPayload = "{YOUR_CUSTOM_PAYLOAD}";
        int quantity = 3;

        IAPV4.purchase(marketPid, iapPayload, quantity, (ResultAPI result, IAPV4Receipt receipt) => {    
        if (result.isSuccess()) {    
                         // TODO: Request verification of receipt with received receipt    
                 }    
});
```

```c++

#include "HiveIAPV4.h"

FString MarketPid = TEXT("YOUR_PRODUCT_MARKET_PID");
FString IapPayload = TEXT("YOUR_CUSTOM_PAYLOAD");
int32 Quantity = 3;

FHiveIAPV4::Purchase(MarketPid, IapPayload, Quantity, FHiveIAPV4OnPurchaseDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveIAPV4Receipt& Receipt) {
                if (Result.IsSuccess()) {
                                // API 呼叫成功
                }
}));
```

API 參考: [IAPV4 ::purchase](http://developers.withhive.com/HTML/v4_api_reference/CPP/group___i_a_p_v4.html#ga2bff8cc9d70d0a25eaddc9d45dac86b8)

```cpp
#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
        using namespace std;    
        using namespace hive;    
        string marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
        string iapPayload = "{YOUR_CUSTOM_PAYLOAD}";
        int quantity = 3;
        IAPV4::purchase(marketPid, iapPayload, quantity, [=](ResultAPI const & result, IAPV4Receipt const & receipt) {    
                 if (result.isSuccess()) {    
                         // TODO: Request verification of receipt with received receipt    
                 }    
});
```

API 參考: [com.hive.IAPV4.purchase](https://developers.withhive.com/HTML/dokka/-hive%20-s-d-k%20v4/com.hive/-i-a-p-v4/purchase.html)

```kt
import com.hive.IAPV4    
        import com.hive.ResultAPI    
        val marketPid = "{YOUR_PRODUCT_MARKET_PID}"    
        val iapPayload = "{YOUR_CUSTOM_PAYLOAD}"
        val quantity = 3
        IAPV4.purchase(marketPid, iapPayload, quantity, object : IAPV4.IAPV4PurchaseListener {    
                 override fun onIAPV4Purchase(result: ResultAPI, iapV4Receipt: IAPV4.IAPV4Receipt?) {    
                         if (result.isSuccess) {    
                                 // call successful    
                         }    
                 }    
})
```

API 參考: [com .hive.IAPV4.purchase](https://developers.withhive.com/HTML/v4_api_reference/Android/group___i_a_p_v4.html#gad5e467681ef02fc2ab393bad201e617c)

```java
import com.hive.IAPV4;    
        import com.hive.ResultAPI;    
        String marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
        String iapPayload = "{YOUR_CUSTOM_PAYLOAD}";
        int quantity = 3;
        IAPV4.INSTANCE.purchase(marketPid, iapPayload, quantity, (result, iapV4Receipt) -> {    
                 if (result.isSuccess()) {    
                         // call successful    
                 }    
});
```

API 參考: [HIVEIAPV4::purchase:additionalInfo:handler:](https://developers.withhive.com/documentation/hiveiapv4/iapv4interface/purchase(_:iappayload:handler:))

```swift
import HIVEService    
        let marketPid = "{YOUR_PRODUCT_MARKET_PID}"    
        let iapPayload = "{YOUR_CUSTOM_PAYLOAD}"
        let quantity = 3

        HIVEIAPV4.purchase(marketPid, iapPayload, quantity) { result, receipt in    
                 if result.isSuccess() {    
                         // TODO: Request verification of receipt with received receipt    
                 }    
}
```

<strong>API 參考</strong>: <a href="[cgv hive_sdk4_ios_api_ref_en]/group___i_a_p_v4.html#ga4cd19176f947717f2c7be545ed76a6e0" target="_blank" rel="noopener noreferrer">HIVEIAPV4::purchase:additionalInfo:handler:</a >

```objc
#import <HIVEService/HIVEService-Swift.h>

NSString *marketPid = @"{YOUR_PRODUCT_MARKET_PID}";
NSString *iapPayload = @"{YOUR_CUSTOM_PAYLOAD}";
NSNumber quantity = 3;

[HIVEIAPV4 購買: marketPid iapPayload: iapPayload 數量 handler: ^(HIVEResultAPI *result, HIVEIAPV4Receipt *receipt) {
        if ([result isSuccess]) {
                // TODO: 使用收到的收據請求驗證
        }
}];
```