Purchase with Midas

Tips: The configuration and management of currency, in-game items, and the store are prerequisite knowledge for reading this article.

1. Overview

1.1 Suitable games

Games published by Tencent can use the payment service provided by Midas to implement the purchase of items or currency in PGOS. Games from other publishing channels can achieve similar functionality through the Third-party Platform Purchase capability provided by PGOS.

1.2 What functionalities does Midas provide?

Games can gain the following capabilities with Midas :

Allowing players to purchase in-game items with cash.
Synchronizing external purchases to PGOS (except for the Steam platform).
Allowing players to purchase in-game currency with cash.
Manage player-paid assets, including cross-platform and isolated player-paid assets.

1.3 Responsibilities of each party

PGOS will integrate with Midas to provide real-money purchasing functionality for games across platforms. After integrating with Midas, the roles of each party involved are as follows:

Midas: Wraps the payment functionality of various platforms, shielding users from the differences in payment channels.
PGOS: Utilizes Midas to enable real-money purchases of in-game items and virtual currency, and help manage paid in-game assets for players.
Game: Integrate Midas SDK and display the store in the game client to the players, allowing them to purchase with real money via Midas client SDK.

1.4 Integration workflow

The integration work of Midas involves operations in both the PGOS portal and the Midas website, which require two different user identities:

PGOS portal: Accessible to any registered user.
Midas website: Currently limited to Tencent employees only.

The main workflow for game integration with Midas is as follows:

Configurations,
- [Midas website] Apply and configure Midas business.
- [Midas website] Configure the Midas add-on on the PGOS portal.
- [PGOS portal] Configure premium currency and item mapping on the PGOS portal.
- [PGOS portal] Publish paid store items on the PGOS portal.
SDK integrate ,
- Integrate the MidasGlobal module provided by the PGOS client SDK.
- Integrate the Midas client SDK to complete the payment.
- Use the PGOS server SDK to modify the player's premium virtual currency balance on demand.
Sandbox testing,
- [Midas website] All objects created in Midas, including tokens, token stalls, products, partitions, and scenes, will be published to the sandbox environment after creation.
- [PGOS portal] Configure the necessary parameters for sandbox environment in the Midas Addon. Note that both Test&Dev Region of PGOS could access Midas sandbox environment.
Release testing,
- [Midas website] All objects created in Midas, including tokens, token stalls, products, partitions, and scenes, should be manually published to release environment.
- [PGOS portal] Configure the necessary parameters for release environment in the Midas Addon. Note that only Prod Region of PGOS could access Midas release environment.

2. Midas Terminology

Midas terminology list

Business

"Business" is the business management unit of Midas that manages products and payment channels. You can think of it as similar to the concept of "Title" in PGOS.

Partition & Role

Midas allows multiple partitions to be defined per business. In different partitions, the same player (Midas user_id) has completely separate accounts, including token balances. PGOS treats Title Regions and Midas Partition as the same level concepts , enabling the same Midas Business to serve all Title Regions in PGOS.

Partition Roles can be used to achieve more granular player account management. Within the same partition, a player (Midas user ID) can have multiple roles, and the player balance for each role is managed separately. PGOS leverages Roles to achieve player token balance management at the granularity of Payment Channels.

Platform & Payment Channels

In Midas, the term "Platform" specifically refers to the four generalized concepts of Apple, Android, PC and Console.

Payment Channels in Midas refer to the entities that provide selling and payment functionalities within each platform. For example:

Steam and Epic are channels within the PC platform.
Playstation, Xbox, and Switch are channels within the Console platform.

Token

Token can be considered as currency in the PGOS concepts. Midas allows games to define multiple types of tokens, and Midas manages the balance of each token for players.

Note: It is crucial that all in-game currencies used for monetization (could purchased by real money) in Tencent- published games must be hosted by Midas.

Player Account & Token Balance

Midas manages the token balance of each player account. A player account consists of four elements: Partition, Role, Platform, and Open ID. This means that when any of the four elements are different, there will be a corresponding separate player account in Midas with its own independent token balance.

Regarding the Platform dimension, Midas provides the Shared option in the Token definition. This option allows users to decide whether to share player balances across platforms (Apple, Android, PC, and Console).

If configured as Share: No matter what platform the player logs into (including all channels within the platform), when other conditions remain the same (which will be explained in detail in the following doc), they will access the same token balance data.
As shown below, when the Platform Shared feature is enabled for a token, players with the same partition in different platforms can share the same token balance. In this case, the constituent elements of the player account will be reduced to: Partition, Role, and Open ID.
If configured as Not to share: When a player logs in to each platform, they will access separate token balance data. However, the balances between different channels within the platform are still shared.
As shown in the diagram below, when the Platform Shared feature for tokens is disabled, the token balance of the same player in different platforms within the same partition will be completely independent.

By default, Midas provides a relatively coarse-grained platform classification. However, games can achieve personalized Midas player account isolation (also known as token balance isolation) based on role IDs. The implementation involves:

Firstly, enable token platform sharing.
With the help of role IDs, you have the freedom to define which sub-platforms share the Midas player account.

As shown below, players use role ID "2" when logging in to platforms such as Playstation, Xbox, PC, and Android. When logging in to Switch and Apple, they use role IDs "1" and "3" respectively. Therefore, the same player will have three accounts across all these sub-platforms, each with a separate token balance.

Note
It is important to note that a player's token balance consists of two parts: the top-up portion and the gift/grant portion. These two parts can only be shared or isolated across platforms as a whole.

Product & Token Stall

Both Product and Token Stall are objects in Midas that can be directly purchased by players.

Product: It is an in-game item that can be purchased by players. Midas does not provide inventory management for Products. After purchasing a Product, Midas will notifie the game server to deliver the product (in-game item in PGOS) through a Webhook callback.
Token Stall: "Token stall" can be imagined as a pile of Midas tokens that can be priced, and players must pay cash to obtain them. After purchasing a Token Stall, Midas will directly grant a certain quantity of tokens to the player's account, and the player's token balance is updated.

Since players ultimately make payments through Payment Channels (such as the Playstation Store), both the Product and Token Stall need to establish mappings with store items in each Channel (which may have different names).

Scene

The scene is also known as Offer App in Midas. Each scene can be configured with channel information of multiple platforms, which Midas will use when accessing the various payment channel services.

Taking the PC platform as an example, you can configure the necessary parameters for payment channels, such as Steam and Epic in the Scene.

The scene helps games and Midas differentiate between bills from different platforms when reconciling. While there are no strict limits on the platforms and channels that can be configured in each scene, Midas officially recommends creating separate scenes for each platform.

Premium Currency

This is a concept provided in PGOS. Unlike virtual currency, premium currency allows players to purchase with cash. Premium currency cannot exist independently and must rely on the paid currency provided by the payment provider, which is Midas Token when the game uses Midas payment service.

PGOS allows games to use premium currency just like Virtual Currency, but the balance of Premium Currency is managed by the payment provider (such as Midas). PGOS will shield users from this discrepancy and keep the functionality, interfaces, and business processes consistent with virtual currency.

Comparison with PGOS

The mapping of terminology between Midas and PGOS is listed below:

Midas terminology	PGOS terminology
Business	Title
Partition	Title Region
Token	Premium Currency
Product / Token Stall	In-game Item

3. Configurations

3.1 Prepare your payment channels

Firstly, you need to complete the preparations in the payment channels, which can be summarized into two parts:

Prepare the necessary channel parameters required in the Midas Scene. These are the necessary parameters for Midas to access the payment channels.
Configure the products in the channels. Most payment channels require the configuration of products and their price information. The player can only complete the payment once Midas has requested the specified product from the payment channel.

Steam

Midas uses the Microtransactions service provided by Steam to complete in-game purchases, which means the game does not need to maintain item configurations in Steam. The Steam parameters required by Midas Scene are listed below::

*NOTE: The API key is the Steam Web API key.*

3.2 Configure Your Midas

3.2.1 Create Midas Business On Midas Console

View the Midas homepage to create a Midas Business exclusively for your game. This part of the work should be completed by dedicated game operators.

It is important to note that if the Platforms provided by Midas natively do not meet your requirements for the insolation of player-paid assets, be sure to enable multi-terminal interworking and partition supports multiple roles when you create Midas Business. Games can use partition roles to achieve more granular control over player-paid asset isolation.

After the creation is complete, review your business information to ensure that the configuration is correct.

3.2.2 Create Tokens

View your Midas business and go to the Tokens management page (Goods > Commodity Library > Tokens). You can browse and manage your tokens here.

Click on New token to create a new token. The key attributes are:

Token share cannot be modified. If you selected Multi-terminal Interworking when creating the business, token share will be enabled by default, which means the token balance of players will be shared across all platforms.
Exchange rate option specifies the exchange rate from currency to token. This parameter is currently known to be used for Midas' security supervision of the business. Please consult the Midas team for more details.

The token you create will be automatically published to the Midas Sandbox and appear on the Tokens page. Midas will assign a Token resource ID to it.

3.2.3 Configure token stall & product

Token stalls and products are both objects that can be directly purchased by players in the Midas system, the difference is:

After purchasing a token stall, tokens will be directly granted to the player's account managed by Midas, increasing the player's token balance.
After purchasing a product, Midas will notify the PGOS backend for delivery through the Webhook configured in the partition.

The process of creating a token stall and a product is very similar, so they are described together below:

Basic information: The basic information of a token stall/product includes name, ID, etc.
- Number of tokens: A specific attribute of a token stall, indicating the number of tokens a player received after purchasing the token stall.
- Props LOGO: A specific attribute of a product, where you can upload an image file.
Price of goods: The price information of a token stall/product in various payment channels. In addition to the prices in different currencies, some channels also require the configuration of platform items, such as the Xbox channel.

Only need to configure the prices in different currencies for the Steam channel since Midas uses the Steam Microtransactions service.

*Note: The country/region parameter is required when creating a Midas order. A country/region that does not have a price set in the token stall/product will be considered an illegal parameter and failed to create a Midas order.

3.2.4 Configure Partition and Delivery Information

Partition

View your Midas business and go to the Delivery/Partition management page (Goods > Delivery/Partition > Partition configuration). Partition is an important parameter for managing player accounts. In Midas, player accounts with different partition IDs are completely isolated. This is similar to the Title Region in PGOS.

You can create partitions under different platforms on demand. Do you remember the Multi-terminal interworking option when creating the business? If this feature is enabled, player accounts with the same partition ID in different platforms can be shared with each other. However, please note that partitions in different platforms must be created separately, and these tasks may be repetitive but unavoidable.

The page for creating a partition is as follows:

Partition ID (first) / Partition ID (second) / Area: these three parameters must be the same.
Account system: select "Tourist".
Callback interface: Used to handle the delivery callback after purchasing a product. It can be modified after creating the partition. We will intruduce how to register callback interfaces later.

Callback API

View your Midas business and go to the Delivery/Partition management page (Goods > Delivery/Partition > Partition configuration). You can find the Callback API Management feature in any platform. Here, you can add or delete callback APIs.

Generally, it is recommended to configure a separate callback API for each partition.

3.2.5 Configure Payment Channels

View your Midas business and go to the Payment Information management page (Channel > Payment Information). Payment channel information is configured in the Scene, click Add a new scene to create one.

Fill in the basic information and select the correct application category:

Select the payment scenes (platforms) you need and fill in the channel parameters:

You will see the created scenes in the Payment scene list.

3.2.6 Using the sandbox

All objects created in Midas, including tokens, token stalls, products, partitions, and scenes, will be published to the Sandbox environment after creation. After the preparations in the sandbox environment are completed, you need to manually publish the created objects or changes to the Release environment, which requires approval from the business administrator for Midas.

PGOS controls the Midas environment accessed by PGOS through the Midas Addon. It is important to note that not all PGOS Title Regions can access the Midas Sandbox for security reasons:

PGOS Test Region	PGOS Dev Region	PGOS Prod Region
*Can* access Midas Sandbox	*Can* access Midas Sandbox	*Can't* access Midas Sandbox

3.3 App keys and shipping keys

3.3.1 Signing and Verifying

Midas is going to verify the signature using RSA algorithm when PGOS invoke the interface. This is a mandatory procedure in Midas system integration. When PGOS sending a request to Midas, signature need to be calculated using private key and Midas will verify the signature using public key. Let's called the pair of keys App keys.

Midas will send notification to PGOS after successful payment or refund, and then PGOS will grant items or revoke the granted items as needed. The notification message sent by Midas to PGOS will also be signed with their private key, using RSA algorithm. To ensure security, PGOS need to verify the signature using the public key provided by Midas, which is called shipping key.

App Keys can be generated by developers and shipping key can be found on Midas portal. App keys and shipping keys need to be configured in PGOS Midas add-on for normal use.

3.3.2 Configure App keys

App keys need to be configured on Midas config page.

Offer id: same as app id
Serial no: just filled in "1"
Env(sandbox): filled in "sandbox"
Env(prod): filled in "release"
Public key(sandbox): sandbox app public key
Public key(prod): production app public key

You can generate App keys using the command below

openssl req  -nodes -new -x509  -keyout server.key
openssl rsa -in server.key -out private.pem
openssl rsa -in server.key -outform PEM -pubout -out public.pem

The private.pem and public.pem is the private key and public key, which for example has the format below:

example private.pem:

example public.pem:

3.3.3 Deploy to Sandbox/Production Environment

You can follow the procedure on Midas config page to deploy the app to sandbox environment. And then deploy to production environment after verification.

3.3.4 Getting Midas Shipping Key

Midas shipping key can be found in "Goods" -> "Delivery/Partition" -> "Shipping configuration" . Then you can configure it in PGOS Midas add-on, which will be described in below section.

3.4 Configure Midas in PGOS

3.4.1 Install Midas addon

PGOS encapsulates the core configurations related to Midas as an Addon, which can be filtered through the Third-party payment tag.

Key parameters:

Business ID: Your Midas business ID. It is recommended that all Title Regions in your PGOS Title share the same Midas Business, because the application cost for Business is relatively high.
Partition ID: Midas partition ID. It is recommended to configure different partition IDs for each PGOS Title Region to ensure that players access different Midas player accounts when logging in to different Title Regions.
Midas Env: Select the Midas environment accessed by PGOS, Sandbox or Prod.
Midas HTTP Domain (Sandbox/Prod): The domain parameter required for PGOS to access the Midas interface.
App Key (Sandbox/Prod): The public and private keys required for PGOS to access the Midas interface, check out the previous section(Configure app keys) for generation and configuration.
Shipping Key (Sandbox/Prod): The public key required by Midas to call the callback webhook, can be found according to previous section(Getting Midas Shipping Key).
Role ID Management: Optional feature.
- When enabled, you can configure the mapping from OS Type + Account Platform to Role ID as needed. PGOS will automatically find the Role ID mapped to the logged-in player's OS Type & Account Platform based on the mapping.
- If this feature is disabled, the game client needs to decide which Role ID to use in the game client and pass it to PGOS through SetMidasGlobalMetaData interface. Whether to use this feature depends on the actual development and operation needs of the game.
Tips: You can learn more details about the application of Role ID in the "Isolation of paid property" section.

3.4.2 Configure your premium currency

Now you can create a premium currency that is bound to a specified Midas token resource ID by specifying the currency type as Midas Global Token when creating a currency. All operations (such as granting, deducting, and consuming) related to this premium currency will be encapsulated by PGOS as operations on the Midas token it is bound to.

3.4.3 Configure platform items

If you want to manage the items purchased through the Midas payment service in the PGOS store, you need to map them to one or more PGOS in-game items, whether they are token stalls or products.

PGOS will locate the specified Midas product through this mapping when creating an order.
After the purchase is completed, PGOS will use the product resource ID provided by Midas callback to locate the definition of the target item in PGOS and deliver it to the player.

The following diagram shows how to create a mapping between PGOS in-game items and Midas token stalls/products:

PGOS does not restrict mapping multiple PGOS in-game items to the same Midas token stall/product.

4. Selling paid items

The preparations have been completed, so let's get to the point and create items that players can access and purchase with real money in the PGOS store.

Items that can be accessed in the PGOS store mean that you need to create a special store item that:

Cannot be purchased with PGOS virtual currency.
Clearly identifies its legitimate purchase channel (Midas).

Items that can be purchased with real money mean that it must be mapped to a Midas product. The game initiates the purchase of the mapped product through the Midas client SDK, and then PGOS grants the in-game item associated with it to the player. Here, you need to consider the following three 'item' concepts and their relationships:

PGOS in-game item: The in-game item is mapped to a Midas token stall/product, and the game displays it to the player through the PGOS store.
Midas token stall/product: Game purchases the token stall or product through Midas.
- For token stalls, Midas directly modifies the player's token balance.
- For products, Midas notifies PGOS of the successful purchase result, and PGOS grants the associated PGOS in-game item to the player.
Pay channel item/offer: Some pay channels require the configuration of item/offer, which is mapped to a token stall or product in Midas. When Midas receives a payment request from a player, it requests the purchase of the item/offer mapped to the token stall or product. After the purchase is completed,
- Midas handles the delivery task for token stalls by itself.
- Midas notifies PGOS through a webhook callback to handle the delivery task for products.

*It is worth noting that Midas uses the Steam Microtransactions service for the PC platform, so there is no need to maintain item information in Steam.*

4.1 Selling paid items

4.1.1 Item configuration

You can create store items that can only be purchased through Midas in any PGOS store. You only need to set the Pay Platform option to Midas Global. The following points should be noted:

The PGOS item that is put on sale should have already established a mapping with a Midas product.
The price configuration of the store item will be disabled in this mode because the pricing in real currency needs to be obtained from Midas. This also means that players cannot purchase the item with PGOS virtual/premium currency.
The deducting prices are not supported for store items with Pay Platform set to Midas Global. Therefore, be careful when handling unique items.

4.1.2Client flow breakdown

sequenceDiagram participant GC as Game Client participant PSDK as PGOS Client SDK participant MSDK as Midas Client SDK rect rgb(191, 222, 253) note right of GC: Preparations GC->>PSDK: [1] call GetMidasGlobalAddonInfo PSDK-->>GC: rsp: Midas global addon info GC->>PSDK: [2] call SetMidasGlobalMetaData GC->>MSDK: [3] call CTIInitialize end rect rgb(191, 222, 253) note right of GC: Build store data GC->>PSDK: [4] call GetStore PSDK-->>GC: rsp: PGOS store info GC->>MSDK: [5] call CTIGetProductInfo MSDK-->>GC: callback: Midas product info end rect rgb(191, 222, 253) note right of GC: Purchase GC->>PSDK: [6] call CreateMidasGlobalOrder PSDK-->>GC: rsp: Midas pay_info GC->>MSDK: [7] call CTIPay MSDK->>MSDK: Player pay on channel UI MSDK-->>GC: callback: pay result end rect rgb(191, 222, 253) note right of GC: Purchase result PSDK-->>GC: [8] Notification: OnInventoryGranted end

Preparations

In this phase, the game client needs to use the PGOS SDK to obtain and set several parameters required by Midas. After that, initializing the Midas SDK.

GetMidasGlobalAddonInfo: This interface retrieves the Midas addon data, which will be used in the CTIInitialize interface.
- role_id: This field is filled by PGOS only when the Role ID Management feature is enabled in the Midas addon.
- partition_id: The partition ID registered in the Midas addon.
- provider_app_id: The provider app ID registered in the Midas addon.
SetMidasGlobalMetaData: Sets the Midas meta data to the PGOS SDK, which will be used in all interfaces involving Midas tokens. The data includes:
- app_id: The Midas offer app ID, taken from the Midas scene.
- platform: The Midas platform enumeration value, which must be one of ANDROID, IOS, WINDOWS (including epic, steam, midaspay), GAME_CONSOLE (including switch, xbox, play station).
- role_id: The Midas Role ID. Each Role ID has its own independent Midas token balance. Note: The game client needs to provide the role ID only when the is_role_id_mapped parameter obtained through the GetMidasGlobalAddonInfo interface is false. Otherwise, this parameter will be ignored.
CTIInitialize: Initializes the Midas SDK. The key parameters are as follows:

    class CTIInitRequest {
    public:
        // SANDBOX or PRODUCTION，must be same with the option on PGOS Addon
        CTI_ENV env;
        // Please obtain this parameter from the relevant personnel at Midas.
        string idcInfo;
        // App offer id for a payment scene.
        string appId; 
        // aka business id.
        string providerAppId;
        // openid need by Midas.
        string userId;
        bool logEnable = false;
        bool isSavaLogFile = false;
        // Payment channel, such as steam, epic or switch.
        CTI_PAYMENT_METHOD paymentMethod;
        // Currency code, refer to ISO 4217.
        string currencyCode; // default is null ，not set value
        // Region code in uppercase, refer to ISO 3166.
        string regionCode; // default is null ，not set value
        string serverId; // partition ID.
        string roleId; // role id.
    };  

Note: Please populate the userId with the account_open_id in the LoginPGOSParams.

Build store data

In this step, the game client needs to pull the information of the products on sale through the PGOS SDK and identify the purchase channel based on the store item attributes. Then, it needs to pull the price information of the paid products through the Midas SDK.

To identify the purchase channel of the store item, use the following structure:

struct StoreItem {
    // "Pgos", make a virtual currency payment to PGOS to purchase this item.
    // "MidasGlobal", make a cash payment through Midas to purchase this item.
    pgos::pstring pay_platform;
    ...
};

You can use the CTIGetProductInfo interface to pull the price information of the Midas token stall/product in batches. Midas allows configuring prices for multiple regions, and this interface returns the corresponding price based on the regionCode field passed during the initialization of the Midas SDK.

CTIProductRequest ctiProductRequest;
ctiProductRequest.unifiedSkuLists.push_back("your_midas_product_id");
CTIPayService::getInstance().CTIGetProductInfo(ctiProductRequest, callbackHandler);

Purchase

The purchase can be completed in two steps:

Call the PGOS CreateMidasGlobalOrder interface to create a Midas payment order. This task is completed by the PGOS backend to ensure security. The interface parameters are as follows:

struct MidasGlobalProductInfo {
    /** Midas unified product id. */
    pgos::pstring midas_unified_product_id;
    /** PGOS store item that mapped to the Midas product and the Store where it will be listed for sale are need. */
    pgos::pstring store_item_id;
    /** PGOS store item that mapped to the Midas product and the Store where it will be listed for sale are need. */
    pgos::pstring store_id;
};

struct MidasGlobalTransaction {
    /** Pay method, enumeration values can be filled in: GOOGLE_PLAY, APPLE_STORE, STEAM, EPIC, MICROSOFT_STORE, SWITCH, PLAY_STATION */
    pgos::pstring payment_method;
    /** Region code in uppercase, refer to ISO 3166. */
    pgos::pstring region_code;
    /** Currency code, refer to ISO 4217. */
    pgos::pstring currency_code;
};

struct CreateMidasGlobalOrderParams {
    /** Purchase item information. */
    MidasGlobalProductInfo product_info;
    /** Transaction information. */
    MidasGlobalTransaction transaction;
    /** Transparent field, with a maximum limit of 256 characters. */
    pgos::pstring payload;
    /** Related to multilingualism, refer to ISO 639-1. */
    pgos::pstring language;
};

Call the Midas CTIPay interface to invoke the payment interface of the pay channel (such as Steam overlay). This interface requires the pay_info data returned by the CreateMidasGlobalOrder interface as input. The interface call is as follows:
```
CTIPayRequest ctiPayRequest;
ctiPayRequest.payInfo = std::string("your pay info");
CTIPayService::getInstance().CTIPay(ctiPayRequest, callbackHandler);
```

Purchase result

The process of delivering the order after payment has been omitted in the previous text. The details are as follows:

sequenceDiagram participant GC as Game Client participant PIS as Pgos Inventory Service participant PSS as Pgos Store Service participant MB as Midas Backend participant PLT as Steam/Epic note right of GC: Omitting the order initiation process. MB->>PLT:Pay PLT->>PLT:Show payment UI PLT->>PLT:Player paid PLT-->>MB:Order paid par a MB-->>GC:Order paid(via Midas Client SDK) and b MB-->>PSS:Order complete notification(Webhook) PSS->>PIS:Grant purchase item PIS-->>GC:Notification: OnInventoryGranted GC->>PIS:Query player inventory end

PGOS uses the OnInventoryGranted event to notify the game client that the purchased items have been obtained. The game needs to pay attention to the src_type field in the event to distinguish the source of the item instance in the event. The details are as follows:

struct InventoryGrantedEvt {
    /** The item instances granted. */
    ItemInstPack item_insts;
    /** Source type of granted. For example, "Store", "Midas", "Portal", "Client", "DS", "VS", "System", "Mail" etc. */
    pgos::pstring src_type;
};

4.2 Selling paid currency

4.2.1 Product configuration

The product configuration method is the same as that of "selling paid items". It should be noted that the PGOS item listed here needs to be mapped to a Midas token stall.

The specific PGOS item is not important at this point. Its role is similar to a placeholder, and the actual purchase is the Midas token stall it is mapped to. After the token stall is purchased, Midas will directly modify the player's token balance.

4.2.2 Client process breakdown

Preparations, Build store data, and Purchase are exactly the same as "selling paid items". Here, we will only introduce the handling of the purchase result.

As mentioned earlier, after the player successfully pays, Midas modifies the player's token balance. Midas does not notify the PGOS backend of this process, so the game should actively query to update the displayed player balance after receiving the successful payment callback.

sequenceDiagram participant GC as Game Client participant PIS as Pgos Inventory Service participant PSS as Pgos Store Service participant MB as Midas Backend participant PLT as Steam/Epic note right of GC: Omitting the order initiation process. MB->>PLT:Pay PLT->>PLT:Show payment UI PLT-->>MB:Order paid MB->>MB:Increase Midas Coin balance for player MB-->>GC:Order paid(via Midas Client SDK) GC->>PIS:Call PGOS SDK GetBalances PIS->>MB:Query Midas Coin balance for player

4.3 Reapply receipt

Midas provides the CTIReapplyReceipt interface. Midas will reprocess the orders for which the player has already paid but the delivery has not been completed after this interface is called. This is generally used to handle two common scenarios:

The player made a purchase in the game, but the delivery was not executed or failed due to internal errors of Midas or PGOS.
The player made a purchase outside the game, and this purchase process does not involve Midas or PGOS, so the delivery cannot be completed immediately.

According to Midas' recommendation, it is suggested that the game call this interface in at least the following two common scenarios to ensure timely completion of the "reapply receipt" operation:

After initializing the Midas SDK,
When the in-game Store interface is invoked.

4.4 Inspect orders

To distinguish from regular store orders, the product orders with pay_platform not equal to Pgos are separated out, and you can browse them in Portal > Economy > Stores > External Orders.

下图是一个 external order 示例，关键信息如下：

Store ID / Store Item ID / In-game Item / Player ID.
Payment Provider: 该订单的支付服务提供商.
External Order ID: 登记在 payment provider 的 order ID.
External Item ID: 购买的 payment provider 中的 item ID. 如 Midas product ID.
Midas Meta Data: 创建order 时填写的 Platform, App ID, Role ID 等参数。
Status：订单当前状态枚举如下：

The following figure shows an example of an external order, with key information as follows:

Store ID / Store Item ID / In-game Item / Player ID.
Payment Provider: The payment service provider for this order.
External Order ID: The order ID registered in the payment provider.
External Item ID: The item ID purchased in the payment provider, such as the Midas product ID.
Midas Meta Data: The Platform, App ID, Role ID, and other parameters filled in when creating the order.
Status: The current status of the order, with the following enumeration:

5. Usage of premium currency

5.1 Consuming Premium Currency

The game can consume the premium currency held by players in two ways:

Deducting the premium currency held by players through interface

PGOS provides interfaces in both the server SDK and HTTP API that can deduct the player's currency. These interfaces can deduct both virtual currency and premium currency:

Server SDK API: SubtractPlayerCurrency
HTTP API: SubtractPlayerCurrency

Each time these interfaces are called, the game needs to fill in the Midas meta data. Unlike the Client SDK, which fills in the Midas meta data at once through the SetMidasGlobalMetaData interface, PGOS cannot reliably obtain or cache this data in the deduction scenario. The data structure is as follows:

/** Meta data for Midas Global. */
struct MidasGlobalMetaData {
    /** Apply Offer id of a Midas payment scenario. */
    pgos::pstring app_id;
    /**
     * Midas Role ID. Each Role ID has its own independent Midas token balance.
     * Note: The game client needs to provide the role ID only when the `is_role_id_mapped` parameter obtained through the GetMidasGlobalAddonInfo interface is false. Otherwise, this parameter will be ignored.
     */
    pgos::pstring role_id;
    /** Platform need by midas payment scenario. Must be one of: ANDROID, IOS, WINDOWS(including epic, steam, midaspay), GAME_CONSOLE(including switch, xbox, play station) */
    pgos::pstring platform;
};

Using premium currency to price store items

You can use premium currency to price store items, and when players purchase these items, their premium currency (such as Midas tokens) will be consumed.

To configure the price information for store items, you need to set the Pay Platform to PGOS when creating the store item.

Then, add the premium currency price for the store item. PGOS does not limit using both virtual currency and premium currency to price store items at the same time.

The game does not need to fill in the Midas meta data actively each time purchasing this item through the PGOS Client SDK. The Client SDK will use the Midas meta data filled in once through the SetMidasGlobalMetaData interface.

5.2 Granting Premium Currency

As mentioned earlier, "PGOS allows games to use premium currency just like virtual currency". Therefore, any method that allows players to obtain virtual currency for free can also be used to obtain premium currency for free. The following are some examples:

Granting through PGOS Server SDK API.
Granting through PGOS HTTP API.
Granting manually from the Portal.
Indirectly granting premium currency as part of a bundle/container.
Indirectly granting premium currency as goals rewards.
Indirectly granting premium currency as mail attachments.

It should be noted that in the scenario of "indirectly granting premium currency as part of a paid bundle/container items", PGOS does not restrict configuring this type of bundle/container as a paid item. That is:

From the player's perspective, this part of the premium currency is obtained through payment, as the player has paid cash to purchase this bundle/container.
From Midas' perspective, this part of the premium currency is given to the player for free, as the player did not obtain this premium currency by purchasing any Midas token stall.

There is no problem with this from a gameplay perspective. However, for game revenue reconciliation, this "premium currency purchased by players" will fall into a gray area. This is because Midas distinguishes tokens obtained by players in different ways by dividing the player balance into topup amount + gift amount.

Therefore, PGOS recommends that games handle the premium currency in bundle/containers with caution to ensure that their behavior is in line with the intended expectations.

6. Isolation of paid property

6.1 Overview

Let's first review the concept of isolating player paid property in Midas:

The above diagram only shows the isolation of token balance, but in fact, after integrating Midas, the game can provide players with two types of paid assets:

Tokens balance managed by Midas: Midas allocates tokens to different Midas player accounts based on the 4-tuple of partition_id, role_id, platform, and open_id filled in when creating a Midas order. When querying the Midas token balance of a player in any scenario, these parameters need to be specified to hit the correct Midas player account. Let us remember this 4-tuple.
In addition, if you have enabled the Multi-Platform feature in Midas business, the platform will not affect the Midas player account, and the 4-tuple will turn into a 3-tuple, that is, partition_id, role_id, and open_id.
If you have configured different Midas partition IDs for different PGOS title regions, you can further exclude the influence of partition_id on the Midas player account, and the 3-tuple will turn into a 2-tuple, that is, role_id, and open_id.
Finally, different PGOS players have different open_ids. Therefore, under the premise of meeting the above constraints, the factor that determines a PGOS player's Midas player account is only the role_id, which is also the recommended way to use Midas by PGOS.
In-game items purchased through Midas managed by the PGOS inventory service: PGOS writes the role_id, platform filled in when creating the Midas order into the item instance obtained by the player. After the game obtains the inventory data, it can use these parameters to distinguish the purchase source of the item instance.

The following will explain how to handle the isolation of player paid property safely in different scenarios.

6.2 From the game client

First, before calling any business interfaces related to Midas tokens or Midas products, be sure to cache the Midas meta data to the PGOS client SDK through the SetMidasGlobalMetaData interface.

/** Meta data for Midas Global. */
struct MidasGlobalMetaData {
    /** Apply Offer id of a Midas payment scenario. */
    pgos::pstring app_id;
    /**
     * Midas Role ID. Each Role ID has its own independent Midas token balance.
     * Note: The game client needs to provide the role ID only when the `is_role_id_mapped` parameter obtained through the GetMidasGlobalAddonInfo interface is false. Otherwise, this parameter will be ignored.
     */
    pgos::pstring role_id;
    /** Platform need by midas payment scenario. Must be one of: ANDROID, IOS, WINDOWS(including epic, steam, midaspay), GAME_CONSOLE(including switch, xbox, play station) */
    pgos::pstring platform;
};

In the game client, there are four scenarios to increase the player's paid property:

Purchasing Midas token stalls or products: In this scenario, all the parameters in the 4-tuple are fixed when the game calls the CreateMidasGlobalOrder interface.
Purchasing bundles containing Midas tokens using PGOS currency: In this scenario, all the parameters in the 4-tuple are fixed when the game calls the CreateStoreOrder interface.
Opening containers containing Midas tokens: In this scenario, all the parameters in the 4-tuple are fixed when the game calls the OpenContainerInstance interface.
Claiming goals rewards or mail attachments: In this scenario, all the parameters in the 4-tuple are fixed when the game calls the ClaimMailAttachment or ClaimGoalReward interface.

You will not see the exposed 4-tuple parameters in the above interfaces because some of them are derived from the cached data of the SetMidasGlobalMetaData interface, and the others are from the Midas addon configuration.

6.3 From the game server

PGOS provides server SDK and HTTP API for game servers to operate player paid property. This mainly includes:

Granting or deducting the player's premium currency
Granting bundles containing premium currency to players

Different from the game client interfaces, each interface that may modify the player's premium currency must be explicitly filled in with MidasGlobalMetaData by the game server

6.4 From the Portal

You can view, modify, and grant premium currency to players in the player details page provided by the Portal. Each operation requires filling in the Midas meta data. The following example shows the granting operation:

When the Midas addon has enabled the Role ID Management feature, the Midas Role ID data needs to be selected from the registered role IDs. Otherwise, it needs to be manually entered.

7. Link Ref

Apply for Midas business configuration change: https://merchant.midasbuy.com/en/operation/joint/changeFlow?templateID=1284
Midas merchant website: https://merchant.midasbilling.com/new/#/

1. Overview​

1.1 Suitable games​

1.2 What functionalities does Midas provide?​

1.3 Responsibilities of each party​

1.4 Integration workflow​

2. Midas Terminology​

Midas terminology list​

Comparison with PGOS​

3. Configurations​

3.1 Prepare your payment channels​

3.2 Configure Your Midas​

3.2.1 Create Midas Business On Midas Console​

3.2.2 Create Tokens​

3.2.3 Configure token stall & product​

3.2.4 Configure Partition and Delivery Information​

3.2.5 Configure Payment Channels​

3.2.6 Using the sandbox​

3.3 App keys and shipping keys​

3.3.1 Signing and Verifying​

3.3.2 Configure App keys​

3.3.3 Deploy to Sandbox/Production Environment​

3.3.4 Getting Midas Shipping Key​

3.4 Configure Midas in PGOS​

3.4.1 Install Midas addon​

3.4.2 Configure your premium currency​

3.4.3 Configure platform items​

4. Selling paid items​

4.1 Selling paid items​

4.1.1 Item configuration​

4.1.2Client flow breakdown​

4.2 Selling paid currency​

4.2.1 Product configuration​

4.2.2 Client process breakdown​

4.3 Reapply receipt​

4.4 Inspect orders​

5. Usage of premium currency​

5.1 Consuming Premium Currency​

5.2 Granting Premium Currency​

6. Isolation of paid property​

6.1 Overview​

6.2 From the game client​

6.3 From the game server​

6.4 From the Portal​

7. Link Ref​