概览

Steam 游戏内支付系统旨在为开发者提供一个能便捷地向用户销售任何商品的渠道，其间用户无需离开游戏。 所销售的商品可完全由商家决定， 这些商品可以是游戏内物品（如武器或弹药）、游戏货币（如钱币或金币），甚至是角色服饰。 您可随意决定游戏内商品的数量，可以单独出售各项物品，也可捆绑成包销售。 Steam 在商品类型或销售方式上没有任何限制，也不会禁止游戏内的其他销售机制。 这一系统的目的是将用户熟悉的 Steam 平台支付体验融入到您的游戏中，使玩家能够方便地直接使用 Steam 钱包余额购买您的商品。 通过这种集成方式，您的游戏可以即时接入新的 Steam 用户和支付方式，无需额外等待。

使用此系统，购买过程完全在您的掌控之中。 对每项购买请求的成功回复，皆可保证从用户处安全扣款，您也能得到确实且及时的通知。 购买获批后，由您决定如何发放和管理物品。 例如，若商品具有时效性，其有效期限完全由您的系统设定。

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

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

游戏内购买的最佳实践

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

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

支付系统的运作方式

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

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

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

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

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

如何建立连接

先决条件

首先，创建一个 WebAPI 发行商密钥。 详细说明请参见使用 Web API 密钥进行验证文档。 此密钥将与所有 Web 服务器请求一起传入，用来验证服务器请求。 这应作为 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 格式返回。 您也可以通过在请求中添加参数“format=xml”来选择返回 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 Web 服务发起购买请求。 您需要使用后文将描述到的 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 来核对结算更新；但如果需要保持服务器的交易数据实时同步，也可以每分钟调用一次，这是完全合理的。
  
  您可以根据需要，通过 ISteamMicroTxn/RefundTxn API 为顾客交易进行退款。 然而，交易可能以其他方式被撤销，这可能需要您的注意。 当交易进入撤销状态（例如，Refunded、PartialRefund、Chargedback、RefundedSuspectedFraud 或 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 来核对结算更新；但如果需要保持服务器的交易数据实时同步，也可以每分钟调用一次，这是完全合理的。
  
  您可以根据需要，通过 ISteamMicroTxn/RefundTxn API 为顾客交易进行退款。 然而，交易可能以其他方式被撤销，这可能需要您的注意。 当交易进入撤销状态（例如，Refunded、PartialRefund、Chargedback、RefundedSuspectedFraud 或 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 - 用户有待处理的交易，该交易必须在开始新的交易之前完成

附录 C：GetReport 类型值

以下为 ISteamMicroTxn/GetReport Web API 所使用的可能“类型”值：

• SETTLEMENT - 应用的所有游戏内交易，包括已退款/拒付的交易，以及授予小额交易物品的 Steam 商店购买。
  
• GAMESALES - 仅包含通过小额交易 API ISteamMicroTxn/InitTxn 启动的交易。
  
• STEAMSTORESALES - 仅包含附带 itemID 的 Steam 商店程序包销售。
  
• CHARGEBACK - 所有因退款或拒付而撤销的游戏内交易。
  
• SUBSCRIPTION - 仅包含已续期的交易。

更多问题？

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