通訊協定標準

這個 API 遵循一套 HTTP API 標準，並且支援 冪等，藉此提升 擷取及準備資料、針對特定領域進行預先訓練 調整指示、離線評估和整合

Google 代管的網址

每種 Google 代管方法的說明文件都會提供基準網址 包含方法名稱和主要版本號碼。完整網址 將呼叫端的付款整合商帳戶 ID 新增到 結尾。例如 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。「精簡序列化」選項 JWE/JWS 支援的功能會處理最終要求主體的編碼。

HTTP 狀態碼

Standard Payments API 的用途是傳回 HTTP 200 狀態碼 適用於所有可由伺服器處理的要求。這包括 成功/拒絕的要求 應用程式邏輯無法處理的要求不應產生 HTTP 200 狀態碼，因為這類狀態碼代表 Google 和 合作夥伴。API 回應應使用適當的 HTTP 狀態 並加上選用的 ErrorResponse 物件。

HTTP 錯誤和原因
400 人	BAD REQUEST 用戶端指定的引數無效。 如果作業因為系統而遭到拒絕，也可以傳回這個引數 不符合執行作業所需的狀態。 如果在系統狀態前重試要求都無法成功，請使用這個代碼 我們已明確修正這個問題舉例來說，如果退款申請失敗 該物件參照的擷取不存在，重試將不會成功 直到整合服務存在於整合商系統中 注意：不得使用 BAD_REQUEST (400) 有適當的應用程式錯誤。適用對象 比方說，幣別不正確時 包含代碼 200 的 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 在作業完成前已過期。適用於符合以下條件的作業 變更系統狀態，那麼即使 作業順利完成。例如，成功的回應 可能因伺服器延遲而延遲 過期。

要求的冪等性

要求的冪等性是標準付款程序的核心策略 用來確保 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 表示 發生錯誤。