协议标准

"时-成功。

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

Google 托管的网址

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

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

如果调用方的付款集成商帐号 ID 是 INTEGRATOR_1,他们会在网址末尾添加此 ID,以形成如下格式:

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/

Google 的正式版基础路径

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

本指南将使用生产端点。

内容类型和编码

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

HTTP 状态代码

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

HTTP 错误和原因
400 BAD REQUEST

客户端指定了无效参数。

如果因系统未处于执行某项操作所需的状态而导致操作遭到拒绝,也可能会返回此代码。

如果在系统状态得到明确修复之前重试请求无法成功,请使用此注解。例如,如果退款请求引用了不存在的照片导致退款请求失败,则在集成商系统中存在相应照片之前,重试不会成功。

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 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 表明此系统出现错误。