典型的 API 流程

下图介绍了用于插入类、保存对象和更新对象的典型通信流程。在您的服务器、网络浏览器和 Google Pay API for Passes 之间进行的所有操作都由您负责实现。虽然下图以会员卡为例，但所有其他卡券均可以使用类似的流程。

图 1. API 流程图。

适用于 JS 按钮和 JWT 网页链接的典型 API 流程

以下概述更详细地介绍了与图 1 相同的过程。其中介绍了 JavaScript (JS) 按钮和 JSON 网络令牌 (JWT) 的典型 API 流程：

  1. 会员卡发卡机构创建 LoyaltyClass。
    1. 您的服务器定义 LoyaltyClass。
    2. 您的服务器发出 POST 请求，以将 LoyaltyClass 插入 Google Pay API for Passes 服务器。
  2. 您的服务器使用相关服务，为特定 LoyaltyClass 的 LoyaltyObject 生成 JWT。此对象代表该用户的会员卡。
    1. 您的服务器使用 JWT 呈现保存到 Google Pay (S2GP) 按钮：
      • 对于网站，使用我们的 JavaScript 按钮。
      • 对于电子邮件、短信和应用，使用含有 S2GP 按钮的 JWT 链接。
  3. 用户点击或点按会员卡发卡机构网站、电子邮件、应用或短信中的保存到 Google Pay。
    1. 用户被引导到着陆页保存 LoyaltyClass 对象。要保存的对象会根据 JWT 呈现于着陆页。如果从应用中点按该按钮，系统会提示用户在 Google Pay 应用中保存对象。
    2. 用户点击发卡机构属性中的保存到 Google Pay，以保存 LoyaltyObject。
    3. 将 LoyaltyObject 插入 Google 服务器，然后推送到 Google Pay 应用。LoyaltyObject 即为“会员卡”。
  4. 发卡机构更新卡片数据：
    1. 会员卡发卡机构使用 Object.id 执行 LoyaltyObject 的 GET 请求。
    2. 会员卡发卡机构更新 LoyaltyObject。
    3. 会员卡发卡机构发出 PUT 或 PATCH 请求，以在 Google Pay API for Passes 服务器中插入已更新的 LoyaltyObject。
    4. LoyaltyObject 将被推送到 Google Pay 应用。

“瘦”JWT 变体

由于浏览器执行的截断，网页链接中使用的 JWT 不得超过 1800 个字符。如果要突破这一限制，您最好事先插入类和对象。然后，JWT 只需要包含“对象 id”字段。

下图展示了将“保存到 Google Pay”按钮添加到电子邮件或短信中的 API 流程。

图 2. 瘦 JWT 图。

JWT POST 请求 API 流程

在保存对象之前，通常很难实现创建和插入类所需的后端工作，但 JWT 可能会超过 1800 个字符的限制。这对于活动门票和登机牌非常有用，其中随着时间的推移会创建许多类。

以航班类为例的流程如下：

  1. 您的服务器为 FlightObject 和 FlightClass 生成一个 JWT。两者都在 JSON 中定义，而且 FlightObject 引用 FlightClass。
  2. 此 JWT 将从您的服务器发送到您的客户端应用，该应用会显示保存到 Google Pay 按钮。请务必使用符合 S2GP 品牌指南的按钮。
  3. 用户点击客户端应用中的 S2GP 按钮。
    1. 向 JWT 端点发出 POST 请求。这将插入类 ID 和对象 ID。如果 JWT 中的类 ID 或对象 ID 已存在于系统中，则不会再次插入它们。如需了解如何更新现有的类和对象，请参阅 API 参考文档。如果已插入类 ID 或对象 ID，则不会抛出任何错误。
    2. 系统为用户打开返回的 URI 响应，以便于其保存卡券。 此 URI 在返回后的一周内有效。

如需实现 API，请参阅使用 JWT POST 请求方法。

图 3. JWT POST 请求示意图。

在图 3 中，保存流程中“您的服务器”和“Google 服务器”之间没有箭头。这是 JWT POST 与 JWT 链接和 Intent 方法之间的根本区别。但是，我们建议您实现服务器到服务器的通信以更新卡券。