通訊協定標準

這個 API 會遵循一組 HTTP API 標準並支援冪等性，以便建立更穩固的整合。

由 Google 代管的網址

每個 Google 代管方法的說明文件都會提供基準網址，當中包含方法名稱和主要版本號碼。透過將呼叫者的付款整合商帳戶 ID 加到末尾，即可建立完整的網址。例如，Google 代管的 echo 方法說明文件會指定下列網址：

https://vgw.googleapis.com/gsp/chargeback-alert-v1/echo

如果呼叫者的付款整合商帳戶 ID 為 INTEGRATOR_1，則會新增至網址結尾：

https://vgw.googleapis.com/gsp/chargeback-alert-v1/echo/INTEGRATOR_1

注意事項：端點說明文件頁面會依據您選用的實作方法提供最準確的網址。

由合作夥伴代管的網址

每個合作夥伴代管 API 方法的說明文件都會提供基準網址，當中包含方法名稱和主要版本號碼。請勿在代管的網址中加入付款整合商帳戶 ID (PIAID)。

沙箱與正式版環境

Google 會將 Chargeback Alert API 代管於沙箱 (用於開發及測試) 和正式版環境。Google 沙箱環境中的要求不會產生任何實際的財務責任。沙箱和正式版環境完全分離，而且不會共用金鑰或交易資訊。

我們會先使用沙箱來測試變更和新功能，因此 Google 預期您的沙箱會長久保持可用狀態。

Google 的沙箱基礎路徑

https://vgw.sandbox.google.com/gsp/

注意事項：如果整合作業已經發布，並會呼叫 https://billpaynotification.sandbox.googleapis.com 主機，則無須採取其他行動。新的整合作業應會呼叫主機「vgw.sandbox.google.com」。

Google 的正式版基礎路徑

https://vgw.googleapis.com/gsp/

注意事項：如果整合作業已經發布，並會呼叫 https://billpaynotification.googleapis.com 主機，則無須採取其他行動。新的整合作業應會呼叫主機「vgw.googleapis.com」。

這份指南會使用正式版端點。

內容類型與編碼

採用 PGP 加密的訊息酬載必須使用 application/octet-stream; charset=utf-8 內容類型。 採用 JWE 加密的訊息酬載必須使用 application/jose; charset=utf-8 內容類型。 您必須使用 rfc4648 §5 中定義的 base64url 編碼來傳送要求內容。

HTTP 狀態碼

Chargeback Alert 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 在作業完成前已過期。針對會變更系統狀態的作業，即使作業成功完成也可能會傳回這個錯誤。舉例來說，雖然伺服器成功提供回應，但因為延遲時間過長而導致超過期限。

要求的冪等性

要求的冪等性是 Chargeback Alert 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 這個系統發生錯誤。