Purchase with Midas

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

1. 概述

1.1 适用游戏

腾讯发行的游戏可以使用 Midas 提供的支付服务来实现在 PGOS 中购买物品或货币。其他发行渠道的游戏可以通过 PGOS 提供的第三方平台购买能力实现类似功能。

1.2 Midas 提供哪些功能？

游戏通过 Midas 可以获得以下能力：

允许玩家使用现金购买游戏内物品。
同步外部购买到 PGOS（Steam 平台除外）。
允许玩家使用现金购买游戏内货币。
管理玩家付费资产，包括跨平台和隔离的玩家付费资产。

1.3 各方职责

PGOS 将与 Midas 集成，为跨平台游戏提供真实货币购买功能。与 Midas 集成后，各参与方的角色如下：

Midas：封装各平台的支付功能，屏蔽用户对支付渠道的差异。
PGOS：利用 Midas 实现游戏内物品和虚拟货币的真实货币购买，并帮助管理玩家的付费游戏资产。
游戏：集成 Midas SDK 并在游戏客户端向玩家展示商店，让玩家可以通过 Midas 客户端 SDK 进行真实货币购买。

1.4 集成流程

Midas的集成工作涉及PGOS门户和Midas网站两个平台的操作，需要两种不同的用户身份：

PGOS门户：任何注册用户均可访问。
Midas网站：目前仅限腾讯员工使用。游戏与Midas集成的主要流程如下：
配置，
- [Midas网站] 申请并配置 Midas业务。
- [Midas网站] 在PGOS门户上配置 Midas插件。
- [PGOS门户] 在PGOS门户上配置 付费货币和 道具映射。
- [PGOS门户] 在PGOS门户上发布 付费商店道具。
SDK集成，
- 集成PGOS客户端SDK提供的MidasGlobal模块。
- 集成 Midas客户端SDK 完成支付。
- 使用PGOS服务端SDK按需修改玩家付费虚拟货币余额。
沙盒测试
- [Midas官网] 在Midas中创建的所有对象，包括代币、代币摊位、产品、分区、场景，创建完成后都会发布到沙盒环境中。
- [PGOS 门户] 在Midas插件中配置沙盒环境必要参数。注意PGOS的Test&Dev Region都可以访问Midas沙盒环境。
发布测试，
- [Midas官网] 在Midas中创建的所有对象，包括代币、代币摊位、产品、分区、场景，都需要手动发布到发布环境。
- [PGOS 门户] 在Midas插件中配置发布环境必要参数。注意只有PGOS的Prod Region才能访问Midas发布环境。

2. Midas 术语

Midas 术语列表

Business：是Midas的业务管理单元，管理产品和支付渠道。你可以认为它类似于 PGOS 中的“ 游戏 ”概念。

Partition & Role

Midas允许每个业务定义多个分区。在不同的分区中，同一个玩家（Midas user_id）拥有完全独立的账户，包括代币余额。 PGOS 将游戏 Regions 和Midas Partition 视为同一层级概念，使同一个Midas Business 可以服务于 PGOS 中的所有游戏 Regions。

分区角色可用于实现更细粒度的玩家账户管理。在同一个分区内，一个玩家（Midas用户 ID）可以拥有多个角色，每个角色的玩家余额分别管理。PGOS 利用角色实现以支付渠道为粒度的玩家代币余额管理。

Platform & Payment Channels 在Midas中，“Platform”一词特指 Apple、Android、PC、控制台四个广义概念。米大师中的支付通道是指在各个平台内提供销售和支付功能的实体。例如：

Steam 和 Epic 是 PC 平台内的通道。
Playstation、Xbox 和 Switch 是控制台平台内的通道。 Token Token 在 PGOS 概念中可以看作是货币。米大师允许游戏定义多种类型的 Token，米大师为玩家管理每种 Token 的余额。
注意：腾讯发行的游戏中用于货币化（可以用真实货币购买）的所有游戏内货币都必须由米大师托管。 玩家账户 & Token 余额 米大师管理每个玩家账户的 Token 余额。玩家账户由四个元素组成：分区、角色、平台和open ID 。这意味着当四个元素中的任何一个不同时，米大师中都会有一个对应的单独玩家账户，并有自己独立的 Token 余额。关于平台维度，米大师在 Token 定义中提供了 Shared 选项。该选项允许用户决定是否跨平台（Apple、Android、PC 和控制台）共享玩家余额。如果配置为共享：无论玩家登录哪个平台（包括平台内所有渠道），在其他条件不变的情况下（后面文档会详细解释），都将访问相同的 token 余额数据。如下所示，当某个 token 开启平台共享功能后，不同平台相同分区的玩家可以共享相同的 token 余额。这种情况下，玩家账户的构成要素将减少为： 分区、角色、 open ID 。

如果配置为不共享：当玩家登录每个平台时，他们将访问独立的代币余额数据。但是，同一平台内不同渠道之间的余额仍然是共享的。

如下图所示，当禁用平台间代币共享功能时，同一分区内同一玩家在不同平台的代币余额将完全独立。

默认情况下，Midas提供相对粗粒度的平台分类。不过，游戏可以基于角色ID实现个性化的Midas玩家账户隔离（也称为代币余额隔离）。具体实现包括：

首先启用代币平台共享。
借助角色ID，您可以自由定义哪些子平台共享Midas玩家账户。

如下图所示，玩家在登录Playstation、Xbox、PC和Android等平台时使用角色ID"2"。在登录Switch和Apple时，分别使用角色ID"1"和"3"。因此，同一玩家在所有这些子平台上将拥有三个账户，每个账户都有独立的代币余额。

注意
需要注意的是，玩家的代币余额由两部分组成：充值部分和赠予部分。这两部分只能作为一个整体跨平台共享或隔离。

商品 & 代币摊位 商品和代币摊位都是Midas中可供玩家直接购买的对象。

商品：是游戏内物品，可供玩家购买。Midas不提供商品的背包管理。购买商品后，Midas会通过Webhook回调通知游戏服务器投放商品（PGOS 中的游戏内物品）。
代币摊位：“代币摊位”可以想象成一堆可以定价的Midas代币，玩家必须支付现金才能获得。购买代币摊位后，Midas会直接向玩家账户中赠予一定数量的代币，并更新玩家的代币余额。由于玩家最终是通过支付通道（比如Playstation 商店）进行支付，所以商品摊位和Token摊位都需要和各个通道中的商店物品建立映射（可能名称不同）。

场景场景在米大师中又称为Offer App，每个场景可以配置多个平台的通道信息，米大师在接入各个支付通道服务时会用到这些信息。

以PC平台为例，可以在场景中配置Steam、Epic等支付通道的必要参数。

场景可帮助游戏和Midas在对账时区分来自不同平台的账单。虽然每个场景中可配置的平台和渠道没有严格限制，但Midas官方建议为每个平台创建单独的场景。

高级货币

这是PGOS提供的一个概念。与虚拟货币不同，高级货币允许玩家使用现金购买。高级货币不能独立存在，必须依赖支付提供商提供的付费货币，当游戏使用Midas支付服务时，这个付费货币就是Midas Token。

PGOS允许游戏像使用虚拟货币一样使用高级货币，但高级货币的余额由支付提供商(如Midas)管理。PGOS会对用户屏蔽这种差异，保持功能、接口和业务流程与虚拟货币一致。

与PGOS的比较

以下列出了Midas和PGOS之间术语的对应关系：

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

3. 配置

3.1 准备支付渠道

首先，您需要在支付渠道完成准备工作，主要包括两个部分：

准备 Midas Scene 所需的渠道参数。这些是 Midas 访问支付渠道所必需的参数。
在渠道中配置商品。大多数支付渠道都需要配置商品及其价格信息。只有当 Midas 向支付渠道请求指定商品时，玩家才能完成支付。

Steam

Midas 使用 Steam 提供的 Microtransactions 服务来完成游戏内购买，这意味着游戏不需要在 Steam 中维护商品配置。以下是 Midas Scene 所需的 Steam 参数：

*注意: API 密钥是 Steam Web API 密钥。*

3.2 配置您的 Midas

3.2.1 在 Midas 控制台创建 Midas Business

访问 Midas 主页为您的游戏创建专属的 Midas Business。这部分工作应由专门的游戏运营人员完成。

需要特别注意的是，如果 Midas 原生提供的平台无法满足您对玩家付费资产隔离的要求，请务必在创建 Midas Business 时启用多端互通和分区支持多角色功能。游戏可以通过分区角色来实现对玩家付费资产更细粒度的隔离控制。

创建完成后，请检查您的企业信息以确保配置正确。

3.2.2 创建代币

查看您的 Midas 业务并进入代币管理页面（商品 > 商品库 > 代币）。您可以在此浏览和管理您的代币。

点击新建代币创建新的代币。主要属性如下：

代币共享无法修改。如果您在创建业务时选择了多端互通，代币共享将默认启用，这意味着玩家的代币余额将在所有平台之间共享。
兑换比例选项指定货币兑换代币的比率。目前已知该参数用于Midas对业务的安全监管。详情请咨询Midas团队。

您创建的代币将自动发布到 Midas Sandbox 并显示在代币页面上。Midas 将为其分配一个代币资源 ID。

3.2.3 配置代币商品和商品

代币商品和商品都是玩家可以在 Midas 系统中直接购买的对象，区别在于：

购买代币商品后，代币会直接发放到 Midas 管理的玩家账户中，增加玩家的代币余额。
购买商品后，Midas 会通过分区中配置的 Webhook 通知 PGOS 后端进行发货。

创建代币商品和商品的过程非常相似，因此下面将一起说明：

基本信息：代币商品/商品的基本信息包括名称、ID 等。
代币数量：代币商品的特有属性，表示玩家购买代币商品后获得的代币数量。
道具 LOGO：商品的特有属性，可以上传图片文件。
商品价格：代币商品/商品在各支付渠道的价格信息。除了不同货币的价格外，部分渠道还需要配置平台物品，如 Xbox 渠道。

由于 Midas 使用 Steam 微交易服务，因此仅需要为 Steam 渠道配置不同货币的价格。

*注意：创建 Midas 订单时，国家/地区参数是必需的。如果代币商店/商品中未设置某个国家/地区的价格，该国家/地区将被视为非法参数，导致 Midas 订单创建失败。

3.2.4 配置分区和发货信息

分区

查看您的 Midas 业务并进入发货/分区管理页面（商品 > 发货/分区 > 分区配置）。分区是管理玩家账号的重要参数。在 Midas 中，具有不同分区 ID 的玩家账号是完全隔离的。这类似于 PGOS 中的游戏区服。

您可以根据需求在不同平台下创建分区。还记得创建业务时的多端互通选项吗？如果启用此功能，不同平台中具有相同分区 ID 的玩家账号可以相互共享。但请注意，不同平台的分区必须分别创建，这些重复性工作可能无法避免。

创建分区的页面如下：

一级分区 ID / 二级分区 ID / 区域：这三个参数必须相同。
账号体系：选择"游客"。
回调接口：用于处理购买商品后的发货回调。可以在创建分区后修改。我们稍后将介绍如何注册回调接口。

回调API

查看您的Midas业务并进入配送/分区管理页面（商品 > 配送/分区 > 分区配置）。您可以在任何平台上找到"回调API管理"功能。在这里，您可以添加或删除回调API。

*通常建议为每个分区配置单独的回调API。

3.2.5 配置支付渠道

查看您的Midas业务并进入支付信息管理页面（渠道 > 支付信息）。支付渠道信息在场景中配置，点击"新增场景"来创建一个场景。

填写基本信息并选择正确的申请类别：

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

选择您需要的支付场景（平台）并填写渠道参数：

您可以在支付场景列表中看到已创建的场景。

3.2.6 使用沙盒环境

在Midas中创建的所有对象，包括代币、代币商店、商品、分区和场景，在创建后都将发布到沙盒环境中。在沙盒环境中完成准备工作后，您需要手动将创建的对象或更改发布到正式环境，这需要Midas业务管理员的审批。

PGOS通过Midas插件控制PGOS访问的Midas环境。需要注意的是，出于安全考虑，并非所有PGOS游戏区域都能访问Midas沙盒环境：

PGOS Test Region	PGOS Dev Region	PGOS Prod Region
可以访问Midas Sandbox	可以访问Midas Sandbox	不能访问 Midas Sandbox

3.3 应用密钥和发货密钥

3.3.1 签名和验证

当PGOS调用接口时，Midas将使用RSA算法验证签名。这是Midas系统集成中的必要步骤。当PGOS向Midas发送请求时，需要使用私钥计算签名，而Midas将使用公钥验证签名。我们将这对密钥称为**应用密钥**。

Midas在支付或退款成功后会向PGOS发送通知，然后PGOS将根据需要发放或撤销已发放的物品。Midas发送给PGOS的通知消息也将使用RSA算法通过其私钥进行签名。为确保安全，PGOS需要使用Midas提供的公钥验证签名，这个公钥被称为**发货密钥**。

**应用密钥**可由开发者生成，**发货密钥**可在Midas门户网站上找到。应用密钥和发货密钥需要在PGOS Midas插件中配置才能正常使用。

3.3.2 配置应用密钥

应用密钥需要在Midas配置页面进行配置。

Offer ID：与应用ID相同
序列号：填写"1"即可
环境(沙箱)：填写"sandbox"
环境(正式)：填写"release"
公钥(沙箱)：沙箱环境应用公钥
公钥(正式)：正式环境应用公钥

您可以使用以下命令生成应用密钥

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

private.pem和public.pem分别是私钥和公钥文件，格式示例如下：

private.pem示例：

example public.pem:

3.3.3 部署到沙箱/生产环境

您可以按照 Midas 配置页面上的步骤将应用部署到沙箱环境。经过验证后，再部署到生产环境。

3.3.4 获取 Midas 运输密钥

您可以在"商品" -> "配送/分区" -> "运输配置"中找到 Midas 运输密钥。然后您可以在 PGOS Midas 插件中进行配置，具体将在下面章节中说明。

3.4 在PGOS中配置Midas

3.4.1 安装Midas插件

PGOS将与Midas相关的核心配置封装为一个插件，可以通过"第三方支付"标签进行筛选。

关键参数：

Business ID：您的Midas业务ID，建议您的PGOS 游戏中所有的游戏 Regions共用同一个MidasBusiness，因为Business的申请成本比较高。
Partition ID：Midas分区ID，建议每个PGOS 游戏区服配置不同的分区ID，以保证玩家登录不同的游戏 Regions时，访问不同的Midas玩家账号。
Midas Env：选择PGOS访问的Midas环境，Sandbox或Prod。
Midas HTTP Domain (Sandbox/Prod)：PGOS访问Midas接口所需的域参数。
App Key (Sandbox/Prod)：PGOS访问Midas接口所需的公钥和私钥，具体请查看上一节(配置app keys)用于生成和配置。
Shipping Key (Sandbox/Prod): Midas 调用回调Webhook所需的公钥，可根据上一节获取 Midas Shipping Key).
角色 ID 管理：可选功能。
- 开启后，您可以根据需要配置 OS Type + 账号平台到角色 ID 的映射，PGOS 会根据映射自动找到登录玩家 OS Type & 账号平台所映射的角色 ID。
- 若关闭该功能，游戏客户端需要自行决定在游戏客户端中使用哪个角色 ID，并通过 SetMidasGlobalMetaData 接口传递给 PGOS。是否使用该功能取决于游戏实际开发运营需求。

温馨提示：您可以在“付费属性隔离”章节了解更多有关角色 ID 应用的详细信息

3.4.2 配置高级货币

现在您可以在创建货币时，通过将货币类型指定为Midas Global Token来创建与特定Midas代币资源ID绑定的高级货币。所有与该高级货币相关的操作（如发放、扣除和消费）都将由PGOS封装为对其绑定的Midas代币的操作。

3.4.3 配置平台物品

如果您想要管理通过 Midas 支付服务在 PGOS 商店中购买的物品，您需要将它们映射到一个或多个 PGOS 游戏内物品，无论是代币商品还是产品。

PGOS 在创建订单时会通过此映射定位指定的 Midas 产品。
购买完成后，PGOS 将使用 Midas 回调提供的产品资源 ID 来定位 PGOS 中目标物品的定义，并将其发放给玩家。

下图展示了如何在 PGOS 游戏内物品和 Midas 代币商品/产品之间创建映射：

PGOS 不限制将多个 PGOS 游戏内物品映射到同一个 Midas 商品/商品档位。

4. 销售付费物品

准备工作已经完成，现在让我们直接进入正题，创建玩家可以在 PGOS 商店中访问并使用真实货币购买的物品。

在 PGOS 商店中可访问的物品意味着您需要创建一个特殊的商店物品，该物品：

不能使用 PGOS 虚拟货币购买。
明确标识其合法购买渠道（Midas）。

可以用真实货币购买的物品意味着它必须映射到 Midas 商品。游戏通过 Midas 客户端 SDK 发起对映射商品的购买，然后 PGOS 将与之关联的游戏内物品授予玩家。在这里，您需要考虑以下三个"物品"概念及其关系：

PGOS游戏内物品：游戏内物品与Midas代币摊位/商品相对应，游戏通过PGOS商店向玩家展示。
Midas代币摊位/商品：游戏通过Midas购买代币摊位或商品。
对于代币摊位，Midas直接修改玩家的代币余额。
对于商品，Midas通知PGOS购买成功的结果，PGOS将相关的PGOS游戏内物品发放给玩家。
支付渠道物品/优惠：某些支付渠道需要配置物品/优惠，这些物品/优惠与Midas中的代币摊位或商品相对应。当Midas收到玩家的支付请求时，会请求购买与代币摊位或商品相对应的物品/优惠。购买完成后，
对于代币摊位，Midas自行处理发货任务。
对于商品，Midas通过webhook回调通知PGOS处理发货任务。

*值得注意的是，Midas在PC平台使用Steam微交易服务，因此无需在Steam中维护物品信息。*

4.1 销售付费商品

4.1.1 商品配置

您可以在任何 PGOS 商店中创建仅能通过 Midas 购买的商品。您只需要将"支付平台"选项设置为"Midas Global"即可。需要注意以下几点：

上架销售的 PGOS 商品必须已经与 Midas 商品建立映射关系。
在此模式下，商店商品的价格配置将被禁用，因为实际货币定价需要从 Midas 获取。这也意味着玩家无法使用 PGOS 虚拟/高级货币购买该商品。
"支付平台"设置为"Midas Global"的商店商品不支持折扣价格。因此，处理独特商品时需要格外注意。

4.1.2 客户端流程分解

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

准备工作

在此阶段，游戏客户端需要使用 PGOS SDK 获取并设置 Midas 所需的几个参数，然后初始化 Midas SDK。

GetMidasGlobalAddonInfo: 该接口获取 Midas 插件数据，将用于 CTIInitialize 接口。
role_id: 仅当在 Midas 插件中启用了角色 ID 管理功能时，PGOS 才会填充此字段。
partition_id: 在 Midas 插件中注册的分区 ID。
provider_app_id: 在 Midas 插件中注册的提供商应用 ID。
SetMidasGlobalMetaData: 设置 Midas 元数据到 PGOS SDK，这些数据将用于所有涉及 Midas 代币的接口。数据包括：
app_id: Midas 场景中的 Midas offer 应用 ID。
platform: Midas 平台枚举值，必须是以下之一：ANDROID、IOS、WINDOWS（包括 epic、steam、midaspay）、GAME_CONSOLE（包括 switch、xbox、play station）。
role_id: Midas 角色 ID。每个角色 ID 都有其独立的 Midas 代币余额。注意：仅当通过 GetMidasGlobalAddonInfo 接口获取的 is_role_id_mapped 参数为 false 时，游戏客户端才需要提供角色 ID。否则，此参数将被忽略。
CTIInitialize: 初始化 Midas SDK。关键参数如下：

    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.
    };  

注意：请使用 LoginPGOSParams 中的 account_open_id 填充 userId。

Build 商店数据

在此步骤中，游戏客户端需要通过 PGOS SDK 获取在售商品信息，并根据商店物品属性识别购买渠道。然后，需要通过 Midas SDK 获取付费商品的价格信息。

要识别商店物品的购买渠道，请使用以下结构：

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;
    ...
};

您可以使用 CTIGetProductInfo 接口批量获取 Midas 代币商品/产品的价格信息。Midas 支持为多个地区配置价格，该接口会根据初始化 Midas SDK 时传入的 regionCode 字段返回相应的价格。

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

购买

购买可以通过以下两个步骤完成：

调用PGOS CreateMidasGlobalOrder 接口创建Midas支付订单。此任务由PGOS后端完成以确保安全。接口参数如下：

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;
};

调用 Midas CTIPay 接口来唤起支付渠道的支付界面（例如 Steam overlay）。该接口需要使用 CreateMidasGlobalOrder 接口返回的 pay_info 数据作为输入。接口调用方式如下：

CTIPayRequest ctiPayRequest;
ctiPayRequest.payInfo = std::string("your pay info");
CTIPayService::getInstance().CTIPay(ctiPayRequest, callbackHandler);

购买结果

在之前的内容中省略了付款后的订单交付流程。具体细节如下：

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 使用 OnInventoryGranted 事件来通知游戏客户端已获得购买的物品。游戏需要关注事件中的 src_type 字段来区分事件中物品实例的来源。具体如下：

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 付费货币销售

4.2.1 商品配置

商品配置方式与"付费道具销售"相同。需要注意的是,此处列出的PGOS道具需要映射到一个Midas代币商品。

具体的PGOS道具在此处并不重要。它的作用类似于一个占位符,实际购买的是它所映射的Midas代币商品。代币商品购买后,Midas会直接修改玩家的代币余额。

4.2.2 客户端流程分解

准备工作、Build商店数据和购买过程与"付费道具销售"完全相同。这里我们只介绍购买结果的处理。

如前所述,玩家支付成功后,Midas会修改玩家的代币余额。Midas不会将这个过程通知PGOS后端,因此游戏在收到支付成功回调后应该主动查询以更新显示的玩家余额。

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 重新提交收据

Midas提供了CTIReapplyReceipt接口。当调用此接口后，Midas将重新处理那些玩家已支付但尚未完成发货的订单。这通常用于处理以下两种常见场景：

玩家在游戏中进行了购买，但由于Midas或PGOS的内部错误导致发货未执行或失败。
玩家在游戏外进行了购买，且该购买过程不涉及Midas或PGOS，因此无法立即完成发货。

根据Midas的建议，建议游戏至少在以下两种常见场景中调用此接口，以确保及时完成"重新提交收据"操作：

在初始化Midas SDK之后，
在调用游戏内商店界面时。

4.4 检查订单

为了与常规商店订单区分开来，pay_platform不等于Pgos的商品订单会被单独列出，您可以在Portal > Economy > Stores > External Orders中浏览这些订单。

下图是一个外部订单的示例，关键信息如下：

商店 ID / 商店物品 ID / 游戏内物品 / 玩家 ID。
付款提供商：此订单的付款服务提供商。
外部订单 ID：在支付提供商中注册的订单 ID。
外部商品ID：在支付提供商处购买的商品ID，例如Midas产品ID。
Midas元数据：创建订单时填写的平台、应用ID、角色ID等参数。
状态：订单的当前状态，具有以下枚举：

5. 高级货币的使用

5.1 消费高级货币

游戏可以通过两种方式消耗玩家持有的高级货币：

通过界面扣除玩家持有的溢价币

PGOS 在服务器 SDK 和 HTTP API 中都提供了可以扣取玩家币的接口。这些接口既可以抵扣虚拟币，也可以抵扣溢价币：

服务器 SDK API：SubtractPlayerCurrency
HTTP API：SubtractPlayerCurrency

每次调用这些接口时，游戏都需要填写Midas元数据。与Client SDK通过SetMidasGlobalMetaData接口一次性填写Midas元数据不同，PGOS在推算场景中无法可靠地获取或缓存这些数据。数据结构如下：

/** 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;
};

使用高级货币为商店商品定价

您可以使用高级货币为商店物品定价，当玩家购买这些物品时，他们的高级货币（例如Midas代币）将被消耗。

要配置商店商品的价格信息，您需要在创建商店商品时将“支付平台”设置为“PGOS”。

然后，添加商店商品的高级货币价格。 PGOS 不限制同时使用虚拟货币和高级货币为商店商品定价。

游戏不需要每次通过PGOS Client SDK购买该物品时主动填写Midas元数据。客户端 SDK 将使用通过 SetMidasGlobalMetaData 接口填写的 Midas 元数据。

5.2 授予高级货币

正如前面提到的，“PGOS允许游戏像虚拟货币一样使用高级货币”。因此，任何能让玩家免费获得虚拟货币的方法也都可以用来免费获得高级货币。以下是一些示例：

通过 PGOS Server SDK API 授予。
通过 PGOS HTTP API 授予。
从门户手动授予。
作为捆绑包/容器的一部分间接授予优质货币。 5.间接授予优质货币作为目标奖励。
以邮件附件的形式间接授予奖励货币。

应当注意的是，在“间接授予高级货币作为付费捆绑包/容器项目的一部分”的场景中，PGOS不限制将此类捆绑包/容器配置为付费项目。那是：

从玩家的角度来看，这部分溢价货币是通过支付获得的，因为玩家已经支付了现金来购买该捆绑包/容器。
从Midas的角度来看，这部分溢价货币是免费提供给玩家的，因为玩家并不是通过购买任何Midas代币摊位来获得这部分溢价货币的。

从游戏玩法的角度来看，这并没有什么问题。但对于游戏收入对账来说，这种“玩家购买的溢价币”将陷入灰色地带。这是因为Midas通过将玩家余额分为“充值金额”+“礼物金额”来区分玩家获得的代币的方式不同。

因此，PGOS 建议游戏谨慎处理捆绑/容器中的高级货币，以确保其行为符合预期。

6. 付费资产隔离

6.1 概述

我们先回顾一下Midas中隔离玩家付费资产的概念：

上图仅展示了代币余额的隔离，但实际上，集成Midas后，游戏可以为玩家提供两类付费资产：

Midas管理的代币余额：Midas根据创建Midas订单时填写的partition_id、role_id、platform、open_id 四元组，将代币分配给不同的Midas玩家账户。在任何场景下查询玩家的Midas代币余额时，都需要指定这些参数，才能命中正确的Midas玩家账户。让我们记住这个四元组。

另外，如果您在Midas业务中启用了多平台功能，则平台不会影响Midas玩家账户，并且四元组将变成三元组，即partition_id、role_id和open_id。

如果您为不同的PGOS标题区域配置了不同的Midas分区ID，则可以进一步排除partition_id对Midas玩家帐户的影响，三元组将变成二元组，即role_id和open_id。

最后，不同的PGOS玩家有不同的open_id。因此，在满足上述约束条件的前提下，决定一个PGOS玩家的Midas玩家账号的因素只有role_id，这也是PGOS推荐的使用Midas的方式。

通过PGOS库存服务管理的Midas购买的游戏内物品：PGOS将创建Midas订单时填写的role_id、platform写入玩家获取的物品实例中。游戏获得库存数据后，可以利用这些参数来区分物品实例的购买来源。

下面将讲解不同场景下如何安全处理玩家付费财产的隔离。

6.2 从游戏客户端

首先，在调用Midas代币或Midas产品相关的业务接口之前，请务必通过“SetMidasGlobalMetaData”接口将Midas元数据缓存到PGOS客户端SDK中。

/** 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;
};

在游戏客户端中，增加玩家付费资产的场景有四种：

购买Midas代币摊位或产品：在这种场景下，当游戏调用CreateMidasGlobalOrder接口时，四元组中的所有参数都是固定的。
使用PGOS货币购买包含Midas代币的捆绑包：在这种情况下，当游戏调用CreateStoreOrder接口时，四元组中的所有参数都是固定的。
打开包含 Midas 代币的容器：在此场景中，当游戏调用OpenContainerInstance接口时，四元组中的所有参数都是固定的。
领取目标奖励或邮件附件：在此场景中，当游戏调用ClaimMailAttachment或ClaimGoalReward接口时，四元组中的所有参数都是固定的。

您不会在上述接口中看到公开的四元组参数，因为其中一些来自“SetMidasGlobalMetaData”接口的缓存数据，其他来自 Midas 插件配置。

6.3 从游戏服务器操作

PGOS 为游戏服务器提供服务器 SDK 和 HTTP API 来操作玩家付费资产。这主要包括：

授予或扣除玩家的高级货币
向玩家授予包含优质货币的捆绑包

与游戏客户端接口不同，每个可能修改玩家奖励货币的接口都必须由游戏服务器显式填写MidasGlobalMetaData

6.4 从门户网站操作

您可以在门户提供的玩家详细信息页面中查看、修改和授予玩家高级货币。每个操作都需要填写Midas元数据。以下示例显示了授予操作：

当 Midas 插件启用角色 ID 管理功能时，需要从注册的角色 ID 中选择“Midas 角色 ID”数据。否则，需要手动输入。

7. 链接参考

申请Midas业务配置变更：https://merchant.midasbuy.com/en/operation/joint/changeFlow?templateID=1284
Midas商户网站：https://merchant.midasbilling.com/new/#/

1. 概述​

1.1 适用游戏​

1.2 Midas 提供哪些功能？​

1.3 各方职责​

1.4 集成流程​

2. Midas 术语​

Midas 术语列表​

与PGOS的比较​

3. 配置​

3.1 准备支付渠道​

3.2 配置您的 Midas​

3.2.1 在 Midas 控制台创建 Midas Business​

3.2.2 创建代币​

3.2.3 配置代币商品和商品​

3.2.4 配置分区和发货信息​

3.2.5 配置支付渠道​

3.2.6 使用沙盒环境​

3.3 应用密钥和发货密钥​

3.3.1 签名和验证​

3.3.2 配置应用密钥​

3.3.3 部署到沙箱/生产环境​

3.3.4 获取 Midas 运输密钥​

3.4 在PGOS中配置Midas​

3.4.1 安装Midas插件​

3.4.2 配置高级货币​

3.4.3 配置平台物品​

4. 销售付费物品​

4.1 销售付费商品​

4.1.1 商品配置​

4.1.2 客户端流程分解​

4.2 付费货币销售​

4.2.1 商品配置​

4.2.2 客户端流程分解​

4.3 重新提交收据​

4.4 检查订单​

5. 高级货币的使用​

5.1 消费高级货币​

5.2 授予高级货币​

6. 付费资产隔离​

6.1 概述​

6.2 从游戏客户端​

6.3 从游戏服务器操作​

6.4 从门户网站操作​

7. 链接参考​