小额交易实现指南 （Steamworks 文献库）

概览

Steam 游戏内支付系统旨在为开发者提供一个能便捷地向用户销售任何商品的渠道，其间用户无需离开游戏。 所销售的商品可完全由店家决定， 可以是游戏内的物品，如武器或弹药、或是游戏中的货币，例如钱币或金钱，甚至是玩家角色的服装。 您可随意决定游戏内商品的数量，可以单独出售各项物品，也可捆绑成包销售。 Steam 在商品类型或销售方式上没有任何限制，也不会禁止游戏内的其他销售机制。 此系统的目的在于将一种用户普遍较熟悉的支付体验，从 Steam 平台带入您的游戏，也让用户能更简便地将 Steam 钱包内的资金消费在您的产品上。 凭借此种类型的整合，您的游戏即能立即面向更多 Steam 用户，并支持更多种可用的支付方式。

使用此系统，购买过程完全在您的掌控之中。 对每项购买请求的成功回复，皆可保证从用户处安全扣款，您也能得到确实且及时的通知。 购买成功之后，您将自行给予并管理售出的物品。 以限时物品为例，物品的有效期限将由您的系统决定。

除了游戏内购买以外，此系统也提供额外功能，可供您的财务与客服系统使用：

顾客付款失败时您会收到通知。
您可通过网页服务提供退款和查询交易状态。
您能通过我们的 Steamstats 合作伙伴站点，实时查看物品和游戏销售的详细报告。

游戏内购买的最佳实践

如果您要在准备上架 Steam 的游戏中使用游戏内购买，我们准备了几项建议、最佳实践，以及一些资源，帮助您做好准备。 无论是免费游戏，还是收费游戏，只要有游戏内购买，在上架前，都有一些共通之处，值得您考虑。

请参见小额交易（游戏内购买）文档，了解更多有关游戏内经济体与最佳实践的建议。

支付系统的运作方式

支付系统结合了您游戏内的购买流程、 Steam 账单网页服务，以及顾客复核流程。

购买流程将以下列顺序进行。 您的用户将始终在您的游戏中开始与完成订单。

您的顾客希望进行游戏内购买时，游戏将传送一项购买请求至您的购买服务器。 购买服务器可以是您的游戏系统用来处理购买请求的任何服务实体。 可以是网页服务器或您的验证系统。 该服务器必须通过 HTTP 与 Steam 账单服务器通信。 另外，您的购买服务器也可向 Steam 账单服务器要求用户的国家/地区、语言和货币信息， 并依此酌情调整定价。
接下来，您的购买服务器将代表客户端向 Steam 网页服务发起付款交易。 该请求将以安全的 HTTP POST 传递。 此请求的内容包括用户希望购买的每一项物品的用户元数据、描述和价格。
收到请求后， Steam 将自动激活 Steam 叠加界面，显示列出所有物品与价格的对话框，以及用来确认或授权交易的按钮。 如果用户的 Steam 帐户余额不足，叠加界面将指引用户至充值流程。 而 Steam 叠加界面将收集并处理用户所有的账单信息。 完成后，用户即会收到购买授权成功或失败的通知。 您的游戏必须设置好接收此通知的回调，并将结果传给购买服务器。
您的购买服务器收到通知后，会发送一个 FinalizeTransaction 调用至 Steam，以完成操作。 响应成功后，将从用户处扣款，您随后即可授予用户该物品。

另外，如果游戏原本就是通过网页销售商品，或是您希望在自己的网站上提供 Steam 作为支付手段，您可选择基于浏览器进行集成。 如使用此方法，购买流程将以下列顺序进行：

用户希望在您的网站上或游戏内进行购买。 如果在游戏内，您须启动浏览器，以打开您的网站。
您的购买服务器将使用安全的 HTTP POST 代表用户发起网络交易。 如成功，将返回一个唯一的 Steam URL，您便可重新导向用户的浏览器会话至此，进行交易授权。 重新导向时，您需指定一个 URL，让用户完成交易授权后回来。
用户回到您的网站后，您的购买服务器将请求获得交易状态。如果授权成功，您可调用 FinalizeTransaction 向 Steam 获取款项。

如何建立连接

先决条件

首先，创建一个 WebAPI 发行商密钥。 详细说明请参见使用 Web API 密钥进行授权文档。 此密钥将与所有网页服务器请求一起传入，用来验证服务器请求。 这应作为 key=<your key here> 参数与请求一起发送。

存储订单

将每项订单存储至您的系统中，以备日后查询。 使用唯一的 64 位订单 ID 查询在 Steam 中的交易。

提交请求

所有请求都必须通过 HTTP 1.1 GET 或 POST 发送，并使用 TLS 加密连接。 内容类型应为“application/x-www-form-urlencoded”，而 POST 参数应位于请求正文，并使用标准 URL 编码格式。 文字传输应使用 UTF-8。

请求将通过此基础 URI 传送：
https://partner.steam-api.com/ISteamMicroTxn/*

有些指令会返回通过或失败的结果。 如果返回的结果为失败，则会追加额外的错误代码和描述。 而如果响应成功，则不会出现这些代码。

响应将默认使用 JSON 格式返回。 可选择指定使用 XML 格式，只需在请求中加入“format=xml”参数。
注意：您必须实现一个灵活的 JSON 或 XML 方案，以便发送和返回任意顺序的参数密钥。

测试

Steam 提供开发者沙盒让您测试自己的集成结果。 沙盒支持所有常规 API 中提供的请求，但不会实际从测试人员的 Steam 钱包中扣款。

沙盒可从另一个基础 URI 访问获得：
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

集成步骤

游戏内购买

此方式适用于有内置商店的游戏，并且用户将在游戏内购物。

第一步
您的游戏需要使用 Steamworks API 发布。 这代表须包含一个头文件、链接至库文件，并随产品发布一个 DLL。 参见 Steamworks API 概览，了解更多信息。 必须先成功初始化 Steamworks API 之后才能继续！
第二步
用户在您的游戏内选择购买一个或多个物品。 物品选定后，您的游戏需要下列几项有关用户的元数据：
Steam ID - 用来在 Steam 系统中识别此用户的唯一的 64 位数字。
国家代码 - 显示用户从哪个国家购买的 ISO 3166 国家代码， 据此来决定售价。
货币代码 - 将使用何种货币扣款的 ISO 4217 货币代码。
客户端游戏语言代码 – Steam 客户端正在以何种语言运行游戏的 ISO 639-1 语言代码。

Steam ID 和语言可通过以下 Steamworks API 调用取得：
ISteamUser::GetSteamID
ISteamApps::GetCurrentGameLanguage

要获得用户的国家/地区和货币类型，可使用 ISteamMicroTxn/GetUserInfo web API 请求传入用户的 Steam ID 。

此用户的元数据应与您的一般购买数据一起发送至购买服务器。

第三步
您的购买服务器代表 Steam 客户端通过 Steam 网页服务发起购买请求。 您需要使用后文将描述到的 ISteamMicroTxn/InitTxn。 请求中必须包含下列数据：
Order ID - 由您为此次购买指定的唯一的 64 位数字。 此数字也是此次交易的键值， 在 Steam 系统中引用该交易时使用。
Steam ID - 第三步中从 Steam 客户端收到的用户 ID 。
App ID - 您的 Steam 游戏的唯一标识符。
语言 - 您的物品所使用的 ISO 639-1 语言代码。
货币 - 您的物品价格所使用的 ISO 4217 货币代码。 如果这与第二步中提供的用户的货币代码不匹配，则将以当前市场汇率自动进行进货币转换。 Steam 将向用户显示转换后的本地货币价格，以供批准。 为了获得最佳的顾客体验，我们建议提供您预期顾客会使用的每种货币的定价。
用户希望购买的物品列表， 每项物品需要指定下列具体数据：
物品 ID - 您的 32 位物品标识符。
数量 - 交易中此类型的物品的数量。
金额 - 您希望收取的物品金额（以百分位为单位）。 部分币种必须以整值定价，参见支持币种，了解更多信息。 如果物品的数量大于一，则此值为要收取的总额（金额 = 数量 x 物品单价）。
物品描述 - 物品的文字描述。 在用户收到的授权交易提示中，将显示此信息。 您可根据 Steam 客户端指定的语言代码将这段描述本地化。
物品类别 - 可选用，描述此物品所属类别的文字。 Steam 后端报表中会使用该值对销售数据进行分组，但绝不会显示给用户。

如果 Steam 接受了这项交易，即会自动通知客户端进行购买授权。 如果返回错误，则需要在修正问题后重新提交一笔购买交易。
第四步
如果 ISteamMicroTxn/InitTxn 尝试成功，用户将会通过 Steam 的游戏内叠加界面收到需要对交易进行授权的通知。 所显示的交易详情将使用购买请求中提供的物品描述。 用户便可授权这项交易。 如果用户的 Steam 帐户余额不足，Steam 将自动引导用户充值。 最后，您的游戏将会收到交易是否授权成功的通知。

您的游戏需要设置 ISteamUser::MicroTxnAuthorizationResponse_t 回调处理程序，以接收授权是否成功的通知。 此回调结果包含 AppID、OrderID，和交易的授权状态。 您的游戏可将此结果发送至购买服务器，以进行交易的最终确认。 请参见回调文档，了解更多信息。

第五步
您的购买服务器将使用 ISteamMicroTxn/FinalizeTxn API 命令，使用下列参数完成交易。
Order ID - 发起交易时创建的订单 ID。
App ID - 您的 Steam 游戏的唯一标识符。

响应成功表示购买被接受，应将物品授予用户。 响应错误表示交易无法完成，并会附上相应的出错信息。
第六步
您的购买服务器将需要频繁调用 ISteamMicroTxn/GetReport API 来接收有关交易结算状态变化的通知。 您应每天至少调用一次此 API 来协调结算更新，但为确保您的服务器与交易更新保持同步，每分钟调用一次此 API 也是可以的。

您可以自行决定使用 ISteamMicroTxn/RefundTxn API 对客户交易进行退款。 但是，还有其他可以撤销交易的方法，可能需要您注意。 当交易进入逆转状态（例如，Refunded、PartialRefund、Chargedback、RefundedSuspsectedFraud 或 RefundedFriendlyFraud - 请参阅：附录 A：状态值）时，如有可能，您的后端应尝试收回与逆转的交易相关联的物品。 请查看我们关于防范欺诈的文献，并确保您已采取措施防范最常见的欺诈类型。

基于网页的购买

如果您的游戏商店建立在网页上，或者您仅希望新增 Steam 作为支付手段，您可按下列步骤进行集成：

第一步
取得用户的 Steam ID。
如果用户正在游戏中，使用此 Steamworks API 返回 Steam ID：ISteamUser::GetSteamID。
如果用户在您的网站上，使用 Steamworks OpenID API 即可安全获取用户的 Steam ID。 有关 OpenID 的详细信息请见 Steamworks 基于网页浏览器的 OpenID 验证文档。

注意： 我们建议您将用户的游戏帐户与其 Steam ID 关联起来，以便用户仅需进行一次这种二次登录。
第二步
调用 ISteamMicroTxn/GetUserInfo Web API，请求传入用户的 Steam ID ，取得用户的国家/地区与货币类型。 此数据可用于在您的商店中为该用户显示相应的定价与币种。

注意： GetUserInfo有一个可选用的 IP 地址参数，可用于向 Steam 提示用户的始发位置。 每次在网页上进行购买或每当用户未经 Steam 客户端登录游戏时，发送用户的公开 IP 地址。

第三步
您的购买服务器通过 Steam Web 服务，使用 ISteamMicroTxn/InitTxn 发起一项购买请求。 除了游戏内常规购买所需数据外，还需要提供两项其他数据：
usersession - 必须设为“web”，表示用户将通过浏览器授权交易。
ipaddress - 用户的公开 IP 地址。

将 usersession 设置为 WEB 后，InitTxn 请求将会返回一个额外的 steamurl 参数。 这是个唯一的 URL，用来重新导向用户的网页会话，并可识别此 API 调用所建立的交易。 第四步
您的购买服务器将用户的网页会话定向至 InitTxn API 调用返回的 Steam URL。 重新定向时，您需附上自己的 URL，作为交易成功（或遭拒）后将用户返回至的地址。 须使用指定的完整 URL（如：http://www.steamgames.com），并使用
returnurl=your_URL_here
格式。
当用户被重新定向至 Steam 的 URL 时，在验证之前必须先登录 Steam。 如果用户是在您的网站上选择使用 Steam 支付，他们会预计看到这样的步骤。 然而，如果用户是经由 Steam 登录游玩您的游戏，则最好能略过二次登录。 使用游戏内叠加界面的内置网页浏览器功能即可达成。 当游戏内叠加界面浏览器用于授权时，用户会自动登录 Steam。 使用 Steamworks API 的
ISteamFriends::ActivateGameOverlayToWebPage
调用即可启动浏览器。
参见此处，了解游戏内叠加界面的使用详情。
第五步
用户回到您的网站后，发出一个 ISteamMicroTxn/QueryTxn API 调用，以获得结果。 如果订单状态为“Approved”（已批准），则可调用 ISteamMicroTxn/FinalizeTxn API 来收取款项。 如果返回了其他任何状态，请终止这次的交易。

注意： 如果用户在中途关闭了浏览器，或发生了任何意外使用户无法返回您的网站，终止此次交易，且不发出 FinalizeTxn 调用。 即使用户批准了该交易，但基于某种原因未被导向回来，也必须终止交易并重新开始。

第六步
您的购买服务器将需要频繁调用 ISteamMicroTxn/GetReport API 来接收有关交易结算状态变化的通知。 您应每天至少调用一次此 API 来协调结算更新，但为确保您的服务器与交易更新保持同步，每分钟调用一次此 API 也是可以的。

您可以自行决定使用 ISteamMicroTxn/RefundTxn API 对客户交易进行退款。 但是，还有其他可以撤销交易的方法，可能需要您注意。 当交易进入逆转状态（例如，Refunded、PartialRefund、Chargedback、RefundedSuspsectedFraud 或 RefundedFriendlyFraud - 请参阅：附录 A：状态值）时，如有可能，您的后端应尝试收回与逆转的交易相关联的物品。 请查看我们关于防范欺诈的文献，并确保您已采取措施防范最常见的欺诈类型。

附录 A：状态值

以下为 ISteamMicroTxn Web API 可能返回的状态值。 带有这些值的响应键通常称为 status。

Init - 已建立订单，但用户尚未授权。
Approved - 用户批准了订单。
Succeeded - 订单已成功处理。
Failed - 订单处理失败或遭拒。
Refunded - 订单已退款，游戏应撤销该产品。 顾客能自行发起退款。
PartialRefund - 购物车中的一个或多个物品已退款。 详情请见各物品的 itemstatus 字段。
Chargedback - 订单存在欺诈或争议，游戏应撤销该产品。
RefundedSuspectedFraud - 因涉嫌欺诈，该订单已被 Valve 退款。 该产品应当由游戏撤销。
RefundedFriendlyFraud - 因被认定为友好欺诈，该订单已被 Valve 退款。 该产品应当由游戏撤销。

附录 B ：错误代码

以下为 ISteamMicroTxn Web API 可能返回的错误代码。 带有这些值的响应键通常称为 errorcode。

1 - 成功
2 - 操作失败
3 - 无效参数
4 - 内部错误
5 - 用户未批准交易
6 - 交易已提交
7 - 用户未登录
8 - 币种与用户的 Steam 帐户币种不符
9 - 帐户不存在，或暂时不可用
10 - 用户拒绝本次交易
11 - 由于用户位于受限制的国家/地区，交易遭拒
12 - 由于扣款协议无效，交易遭拒
13 - 由于扣款协议不属于 GAME 类型，无法处理
14 - 由于支付纠纷或拒付，扣款协议被搁置
15 - 由于扣款协议非 STEAM 类型，无法处理
16 - 用户已拥有此游戏的扣款协议
100 - 余额不足
101 - 超过交易最终确认的时限
102 - 帐户已停用
103 - 帐户无购买许可
104 - 交易因检测到欺诈被拒绝
105 - 无缓存的支付方式
106 - 交易金额超过扣款协议的额度限制
107 - 用户有待处理的交易，该交易必须在开始新的交易之前完成

更多问题？

如有任何疑问，请前往游戏内购买集中讨论区。

相关知识

小额交易实现指南 （Steamworks 文献库）
小额交易（游戏内购买） （Steamworks 文献库）
Steam 云畅玩（测试版） （Steamworks 文献库）
用户评测 （Steamworks 文献库）
Steam 叠加界面 （Steamworks 文献库）
在 Steam 商店实况直播游戏试用版 （Steamworks 文献库）
Python实现战棋游戏策略算法：从入门到进阶的编程指南
破天一剑账号交易app哪个好用 正规的游戏号交易软件指南
库鲁启动手游新手入坑必看指南
欧陆战争5帝国文献怎么刷-刷帝国文献方法攻略一览

网址: 小额交易实现指南 （Steamworks 文献库） http://www.hyxgl.com/newsview341786.html