一般 API 流程

下圖說明用來插入類別、儲存物件及更新物件的一般通訊流程。您必須負責建置伺服器、網路瀏覽器和 Google Pay API for Passes 之間的所有動作。下圖使用「會員」票證做為範例，但所有其他「票證」多半都會使用類似的流程。

圖 1. API 流程圖。

JS 按鈕和 JWT 網頁連結適用的一般 API 流程

以下大綱將詳細說明與圖 1 相同的程序，其中涵蓋 JavaScript (JS) 按鈕和 JSON Web Token (JWT) 適用的一般 API 流程：

1. 會員卡核發機構建立 LoyaltyClass。
1. 您的伺服器定義 LoyaltyClass。
2. 您的伺服器發出 POST 要求，藉此在 Google Pay API for Passes 伺服器中插入 LoyaltyClass。
注意：如果使用 JS 按鈕，這個步驟不一定適用。由於沒有任何字元限制，您並不需要預先插入類別；只是如果預先插入了類別，您就得以重複使用，所以我們還是會建議這樣做，而這通常也是處理會員卡的最佳方式。
2. 您的伺服器有項服務，能針對特定 LoyaltyClass 產生 LoyaltyObject 的 JWT。這個物件代表使用者的會員卡。
1. 您的伺服器使用 JWT 呈現 [儲存至 Google Pay] (S2GP) 按鈕：
• 如為網站，請使用我們的 JavaScript 按鈕。
• 如為電子郵件、簡訊和應用程式，請使用含有「儲存至 Google Pay」按鈕的 JWT 連結。
3. 在會員卡核發機構的網站、電子郵件、應用程式或簡訊中，使用者按一下或輕觸 [儲存至 Google Pay]。
1. 系統將使用者帶往到達網頁，以便儲存 LoyaltyClass 物件。到達網頁中會依據 JWT 顯示要儲存的物件。如果使用者是在應用程式中輕觸按鈕，系統會提示將物件儲存至 Google Pay 應用程式。
2. 使用者按一下核發機構資源中的 [儲存至 Google Pay]，即可儲存 LoyaltyObject。
3. 系統將 LoyaltyObject 插入 Google 伺服器，然後推送至 Google Pay 應用程式。LoyaltyObject 稱為「會員票證」。
注意：在使用者執行的儲存作業或伺服器 REST 第一次插入 LoyaltyClass 或 LoyaltyObject 之後，後續具有相同 classID 或 objectID 的 JWT 會顯示 Google 伺服器中已插入的內容。如果您針對現有 classID 或 objectID 變更 JWT 中的資訊，系統不會更新該項資訊。如要瞭解如何更新現有類別和物件，請參閱步驟 4。
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 就只需要包含「object id」欄位。

注意：請在使用者表示要將票證儲存至 Google Pay 後，再插入類別和物件。如要啟動精簡的 JWT 儲存流程，建議您定義自己的儲存連結。

下圖顯示將 [儲存至 Google Pay] 按鈕新增至電子郵件或簡訊的 API 流程。

圖 2. 精簡的 JWT 圖表。

JWT POST 要求 API 流程

在儲存物件之前要實作建立及插入類別所需的後端工作，通常相當困難；但為了避免 JWT 長度超過上限 1800 個半形字元，也只能勉為其難。對於活動票券和登機證這類會隨著時間建立許多類別的票證，這種方式最為適用。

注意：從應用程式儲存物件時，您可以使用 JWT POST 要求方法，但由於這個方法使用 POST 呼叫，因此無法在簡訊或電子郵件中使用。

以下用航班類別為例顯示此流程：

1. 您的伺服器針對 FlightObject 和 FlightClass 產生 JWT。這兩個項目都是在 JSON 中定義，而且 FlightObject 會參照 FlightClass。
2. 您的伺服器會將這個 JWT，傳送到顯示 [儲存至 Google Pay] 按鈕的用戶端應用程式。請務必使用符合「儲存至 Google Pay」品牌規範的按鈕。
3. 使用者在用戶端應用程式中按一下 [儲存至 Google Pay] 按鈕。
   1. 系統向 JWT 端點發出 POST 要求，此動作會插入類別 ID 和物件 ID。如果 JWT 中的類別 ID 或物件 ID 已存在於系統中，則不會再次插入這些項目。請參閱我們的 API 參考資料說明文件，瞭解如何更新現有類別和物件。如已插入這些項目，則不會顯示任何錯誤。
   2. 系統開啟傳回的 URI 回應，以便使用者儲存票證。這個 URI 在傳回後具有一週的效期。

如要實作 API，請參閱使用 JWT POST 要求方法的說明。

圖 3. JWT POST 要求圖表。

在圖 3 的儲存流程中，「Your Server」(您的伺服器) 和「Google Server」(Google 伺服器) 之間沒有任何箭頭。這就是 JWT POST 和 JWT 連結與意圖方法之間的主要差異。不過，我們仍建議你實作伺服器間的通訊以更新票證。