這個 API 會遵循一組 HTTP API 標準並支援冪等性，以便建立更穩固的整合。
由 Google 代管的網址
每個 Google 代管方法的說明文件都會提供基準網址，當中包含方法名稱和主要版本號碼。透過將呼叫者的付款整合商帳戶 ID 加到末尾，即可建立完整的網址。例如，Google 代管的 echo 方法說明文件會指定下列網址：
https://vgw.googleapis.com/gsp/refundable-one-time-payment-code-v1/echo
如果呼叫者的付款整合商帳戶 ID 為 INTEGRATOR_1，則會新增至網址結尾：
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 這個系統發生錯誤。