此 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/
Google 的生产基础路径
https://vgw.googleapis.com/gsp/
本指南将使用生产端点。
内容类型和编码
使用 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
客户端指定了无效参数。 如果因为系统未处于执行某项操作所需的状态而导致操作遭到拒绝,也可能会返回此代码。 如果在系统状态得到明确修正之前重试请求无法成功,请使用此代码。例如,如果退款请求引用了不存在的照片导致退款请求失败,则在集成商系统中存在相应照片之前,重试不会成功。
|
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:收到响应前连接中断
场景:
- Google 向集成商发送捕获请求。
- 集成商服务器收到此请求,并成功处理。
- Google 的服务器在收到第 2 步中的响应之前断电。
- Google 的服务器电源恢复,并使用所有相同参数(相同请求 ID 和请求详细信息,但更新了
requestTimestamp
)向集成商服务器发送相同的捕获请求。
结果:
在这种情况下,集成商服务器必须使用与第 2 步相同的回复进行回复,因为除 responseTimestamp
以外的所有参数都相同。用户只在第 2 步被扣款一次。第 4 步对用户没有金额上的影响。
示例 2:请求发送到正在维护的服务器
场景:
- 集成商服务器的数据库停机维护。
- Google 向集成商发送请求。
- 集成商正确返回
UNAVAILABLE
状态代码。 - Google 服务器收到响应并安排重试。
- 集成商服务器的数据库恢复在线状态。
- Google 重新发送第 2 步涉及的请求(请求 ID 和请求详细信息相同,但更新了
requestTimestamp
)。请注意,两个请求的请求 ID 应该相同。 - 集成商服务器收到请求并返回完整的响应及 OK 状态代码。
结果:
在这种情况下,集成商服务器必须在第 7 步处理请求,而不应返回 HTTP 503
(UNAVAILABLE
);集成商服务器应该完整地处理请求,并返回 OK 及合适的消息。请注意,当系统处于 UNAVAILABLE
状态时,Google 可能会发出类似于第 2 步的重复请求。每个请求都应该生成类似于第 3 步的消息。
最终将发生第 6 步和第 7 步。
示例 3:由于恢复错误,重试的消息与初始消息不匹配
场景:
- Google 向集成商发送请求。
- 集成商服务器收到此请求,并成功处理。
- Google 的服务器在收到第 2 步中的响应之前断电。
- Google 的服务器电源恢复并尝试发送相同的请求,但遗憾的是,部分参数不同。
结果:
在这种情况下,集成商服务器应回复 HTTP 412
(PRECONDITION FAILED
) 错误代码,以向 Google 说明此系统出现错误。