协议标准

此 API 遵循一组 HTTP API 标准，并且支持幂等性，以实现更强大的集成。

Google 托管的网址

每种 Google 托管方法的文档都提供一个基准网址，其中包含方法名称和主版本号。将调用者的付款集成商帐号 ID 添加到末尾可以创建完整网址。例如，Google 托管的 echo 方法的文档指定了以下网址：

https://vgw.googleapis.com/gsp/refundable-one-time-payment-code-v1/echo

如果调用者的付款集成商帐号 ID 为 INTEGRATOR_1，他们将在上述网址末尾添加该 ID，从而生成以下完整网址：

https://vgw.googleapis.com/gsp/refundable-one-time-payment-code-v1/echo/INTEGRATOR_1

注意：有关您正在实现的具体方法的端点文档页面将提供适合您情况的最准确的网址。

合作伙伴托管的网址

每种合作伙伴托管的 API 方法的文档都提供一个基准网址，其中包含方法名称和主版本号。您不应在您托管的网址中添加付款集成商帐号 ID (PIAID)。

沙盒环境和生产环境

Google 在沙盒环境（用于开发和测试目的）和生产环境中托管 One Time Payment Code API。Google 沙盒环境中的请求不会产生任何实际的财务责任。沙盒环境和生产环境完全独立，不会共享密钥或事务信息。

Google 会假定您的沙盒是始终可用的，因为我们将首先使用沙盒测试更改和新功能。

Google 的沙盒基础路径

https://vgw.sandbox.google.com/gsp/

注意：：如果集成已启动并调用 https://billpaynotification.sandbox.googleapis.com 主机，您可以继续执行操作。新的集成应调用“vgw.sandbox.google.com”主机。

Google 的生产基础路径

https://vgw.googleapis.com/gsp/

注意：如果集成已启动并调用 https://billpaynotification.googleapis.com 主机，您可以继续执行操作。新的集成应调用“vgw.googleapis.com”主机。

本指南将使用生产端点。

内容类型和编码

使用 PGP 加密的消息载荷必须使用内容类型 application/octet-stream; charset=utf-8。 使用 JWE 加密的消息载荷必须使用内容类型 application/jose; charset=utf-8。 如 rfc4648 §5 所定义，请求正文必须使用 base64url 编码发送。

HTTP 状态代码

One Time Payment Code API 旨在针对服务器可处理的所有请求返回 HTTP 200 状态代码。这包括从业务或应用逻辑角度出发的成功请求和遭拒的请求。无法处理的请求不会产生 HTTP 200 状态代码，因为它们表示 Google 与合作伙伴之间存在错误。API 响应应将下面合适的 HTTP 状态代码与可选的 ErrorResponse 对象结合使用。

HTTP 错误和原因
400	BAD REQUEST 客户端指定了无效参数。 如果因为系统未处于执行某项操作所需的状态而导致操作遭到拒绝，也可能会返回此代码。 如果在系统状态得到明确修正之前重试请求无法成功，请使用此代码。例如，如果退款请求引用了不存在的照片导致退款请求失败，则在集成商系统中存在相应照片之前，重试不会成功。 注意：如果存在相应的应用错误，则不得使用 BAD_REQUEST (400)。例如，如果标准响应中包含字段或枚举值，则不正确的货币应返回代码为 200 的 ACCOUNT_DOES_NOT_SUPPORT_CURRENCY。
401	UNAUTHORIZED 请求没有执行相应操作的有效身份验证凭据。例如，无效的签名或未知签名应返回 401。
403	FORBIDDEN / PERMISSION DENIED 调用者无权执行指定的操作。
404	NOT FOUND 未找到所请求的实体（例如付款或用户）。
409	CONFLICT / ABORTED 操作被取消，这通常是由定序器检查故障、交易取消等并发问题引起的。
412	PRECONDITION FAILED 此代码应用于不同参数重复使用幂等密钥的情况。
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS 一些系统资源已用尽。
499	CANCELLED 操作已取消（通常是被调用者取消）。
500	INTERNAL ERROR 内部错误。这意味着底层系统所期望的一些不变量已损坏。
501	UNIMPLEMENTED 操作在此服务中未实现、不受支持或未启用。
503	UNAVAILABLE 该服务目前不可用。这很可能是一种暂时性情况，可以通过重试来更正。
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED 在操作完成之前截止期限已过。对于更改系统状态的操作，即使操作已成功完成，也可能会返回此错误。例如，服务器的成功响应延迟时间过长，截止期限已过。

请求幂等性

请求幂等性是 One Time Payment Code API 中使用的核心策略，用于确保 Google 与合作伙伴之间的系统交互保持良好并具有容错能力。幂等请求可能会发送多次，但与单个请求具有相同的影响。此策略通过确保重试的安全性来促进系统之间的最终一致性，使我们的系统在资源状态方面保持一致。

我们的 API 利用幂等性实现以下目的：

• 让所有操作都易于跟踪和审核，从而减少对帐问题。
• 通过确保来自同一客户端的多个相同请求不会产生不同的最终状态，防止出现竞态条件。
• 通过仅允许孤立地理解请求，尽可能减少状态数量，这样可以移除由于数据保留引起的服务器负载，从而提升性能和吞吐量。
• 无需使用额外的字段来指示请求是否为重试

注意：错误结果不得缓存或以幂等方式返回。此外，由于错误而自动进行重试时，必须使用指数退避算法策略。

示例

示例 1：收到响应前连接中断

场景：

1. Google 向集成商发送捕获请求。
2. 集成商服务器收到此请求，并成功处理。
3. Google 的服务器在收到第 2 步中的响应之前断电。
4. Google 的服务器电源恢复，并使用所有相同参数（相同请求 ID 和请求详细信息，但更新了 requestTimestamp）向集成商服务器发送相同的捕获请求。

结果：

在这种情况下，集成商服务器必须使用与第 2 步相同的回复进行回复，因为除 responseTimestamp 以外的所有参数都相同。用户只在第 2 步被扣款一次。第 4 步对用户没有金额上的影响。

示例 2：请求发送到正在维护的服务器

场景：

1. 集成商服务器的数据库停机维护。
2. Google 向集成商发送请求。
3. 集成商正确返回 UNAVAILABLE 状态代码。
4. Google 服务器收到响应并安排重试。
5. 集成商服务器的数据库恢复在线状态。
6. Google 重新发送第 2 步涉及的请求（请求 ID 和请求详细信息相同，但更新了 requestTimestamp）。请注意，两个请求的请求 ID 应该相同。
7. 集成商服务器收到请求并返回完整的响应及 OK 状态代码。

结果：

在这种情况下，集成商服务器必须在第 7 步处理请求，而不应返回 HTTP 503 (UNAVAILABLE)；集成商服务器应该完整地处理请求，并返回 OK 及合适的消息。请注意，当系统处于 UNAVAILABLE 状态时，Google 可能会发出类似于第 2 步的重复请求。每个请求都应该生成类似于第 3 步的消息。 最终将发生第 6 步和第 7 步。

示例 3：由于恢复错误，重试的消息与初始消息不匹配

场景：

1. Google 向集成商发送请求。
2. 集成商服务器收到此请求，并成功处理。
3. Google 的服务器在收到第 2 步中的响应之前断电。
4. Google 的服务器电源恢复并尝试发送相同的请求，但遗憾的是，部分参数不同。

结果：

在这种情况下，集成商服务器应回复 HTTP 412 (PRECONDITION FAILED) 错误代码，以向 Google 说明此系统出现错误。