协议标准

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

Google 托管的网址

每种 Google 托管的方法的文档都提供了一个基准网址， 包括方法名称和主要版本号。创建了完整网址 方法是将调用方的付款集成商账号 ID 添加到 end 的值。例如，Google 托管的 echo 方法的文档 指定网址：

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

如果调用方的付款集成商账号 ID 为 INTEGRATOR_1，则调用方应添加 添加到网址末尾：

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

注意 ：您要访问的特定方法对应的端点文档页面 实现将针对您的支持请求提供最准确的网址。

合作伙伴托管的网址

每种合作伙伴托管的 API 方法的文档都提供了一个基准网址， 包括方法名称和主要版本号。请勿在广告中包含 付款集成商账号 ID (PIAID) 。

沙盒环境和生产环境

Google 在沙盒中同时托管 Standard Payments API（用于开发和 测试）和生产环境。Google 沙盒环境中的请求 不会产生任何现实的财务责任。沙盒和 生产环境是完全独立的，不会共享密钥或 交易信息。

Google 希望您的沙盒始终可用，因为我们将使用 测试区，首先测试更改和新功能。

Google 的沙盒基本路径

https://vgw.sandbox.google.com/secure-serving/gsp/

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

Google 的生产基础路径

https://vgw.googleapis.com/secure-serving/gsp/

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

本指南将使用生产端点。

内容类型和编码

使用 PGP 加密的消息载荷必须使用内容类型 application/octet-stream; charset=utf-8。PGP 请求正文必须 使用 base64url 编码发送，如 rfc4648 §5。 使用 JWE 加密的消息载荷必须使用内容类型 application/jose; charset=utf-8。紧凑序列化选项 处理最终请求正文的编码。

HTTP 状态代码

Standard Payments API 旨在返回 HTTP 200 状态代码 。这包括 从业务角度来看待解决的请求 应用逻辑无法处理的请求不应导致 HTTP 200 状态代码，因为它们表示 Google 和 合作伙伴。相反，API 响应应使用相应的 HTTP 状态， 并添加一个可选的 ErrorResponse 对象。

HTTP 错误和原因
400	BAD REQUEST 客户端指定了无效参数。 如果操作因系统错误而被拒绝， 未处于操作执行所需的状态。 如果重试请求在系统进入状态之前无法成功，则使用此方法 已明确修正例如，如果退款申请因以下原因而失败： 它引用了不存在的捕获，重试不会成功 直到捕获出现在集成商系统中。 注意：不得使用 BAD_REQUEST (400) 出现适当应用错误的情况。对于 例如，不正确的货币应返回 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 截止期限已过，操作还未完成。对于 更改系统状态，那么即使 操作成功完成。例如，成功响应 从服务器发出的请求可能会延迟很长时间，以至于需要处理 过期。

请求幂等性

请求幂等性是 Standard Payments 中使用的核心策略 用于确保 Google 与合作伙伴之间的系统互动 稳健且容错。幂等请求是指 可能会多次发送，但与单个请求的效果相同。 此策略通过确保两个系统之间的最终一致性， 这样，我们的系统就可以就 资源状态

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

• 通过使所有操作易于跟踪和减少， 可审核。
• 确保来自某个外部 IP 地址的多个相同请求 同一客户端不会产生不同的最终状态。
• 允许单独理解请求，从而尽可能减少状态， 通过消除由 数据的保留。
• 无需使用额外字段来指示请求是否为重试

。

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

示例

示例 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）。请注意，这两个请求 应该相同
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 指明存在 错误。