總覽
Google Standard Payments 支援現金交易付款方式 (例如付款方式),例如在便利商店 (例如 7-Eleven) 消費。整體來說,想支付商品費用的使用者會透過付款整合商產生參考編號。接著,使用者將這個參考編號帶往便利商店、資訊站或銀行,並支付該參考號碼。
概念與術語
{setvar <顏色> 付款結果。付款詳情符號和會議
針對這些文件中「必須」、「不得」、「必要」、「應」、「不應」、「應該」、「建議」、「可能」和「選用」等重要字詞,均以 RFC 2119 的說明表示。
時間戳記
所有時間戳記都以毫秒表示,自世界標準時間 Unix 紀元 (1970 年 1 月 1 日) 起。
例如:
- 2019 年 4 月 23 日下午 8:23:25 (GMT = 1556051005000 毫秒)
- 2018 年 8 月 16 日下午 12:28:35 (GMT = 1534422515000 毫秒)
金額
這個 API 中的金額值會採用「微量」的格式,也就是 Google 的標準。微量是以整數為準的固定精確度格式。如要以微量單位表示金額,請將標準貨幣值乘以 1,000,000。
例如:
- $1.23 美元 = 12,30000 微秒
- $0.01 美元 = 10,000 微秒
冪等
這個 API 中的所有方法呼叫都必須具有冪等行為。Google 會定期重試要求,確保兩方的交易狀態相同。整合商不得嘗試重新處理任何已順利處理完畢的要求。請改為回報成功處理的回應。所有方法都有共用的 RequestHeader
,其中包含 requestId。requestId 是所有呼叫的冪等鍵。
任何非終端機回應 (HTTP 200 失敗) 都不得以冪等方式處理。因此,如果先前收到 400 (廣告請求錯誤/失敗的先決條件) 一次,第二次呼叫時,就不能以冪等方式傳回 400,就必須重新評估。重新評估時,系統可能會傳回 400 錯誤,或已成功處理。
如要進一步瞭解冪等性,請參閱這份詳細指南。
整合商
使用 Google 付款平台為自家業務的公司。客戶可以是 YouTube 或 AdWords 等內部 (第一方),也可以是想將服務整合到 Google 生態系統的外部 (第三方) 商家。
付款方式
付款方式。這比樂器一般。Visa、MasterCard 和 PayPal 都是 FOP。
方式
特定客戶適用的付款方式。例如使用者的信用卡或 PayPal 帳戶。針對特定客戶,代碼化 FOP 也是其中一種方式,因為其是一種客戶的付款方式,可以安全地儲存在我們的系統中。
權杖
代表特定使用者付款方式的 Google 系統代表。因為其中包含購買所需的所有資訊,而憑證也是付款方式。這可能包括使用者在整合商中所擁有的帳號。
主要流程
Google 會使用以下兩個主要流程來建立和支付這些參考編號:
- 產生參考編號流程。
- 付款參考編號流程。
之後購買交易的對帳和和解事宜將由匯款流程處理。
下圖說明每個流程。
現金 FOP 總覽
以下各節將進一步說明前兩個流程。如要進一步瞭解該流程,請參閱匯款流程頁面。
產生參考編號
產生參考編號流程的目的是建立並交換所需的識別碼 (參考編號),讓 Google 和整合商用於識別購買交易。如此一來,使用者可以在便利商店、資訊站或銀行中使用這組參考編號完成交易。整合者必須呼叫 generateReferenceNumber
方法,才能依 Google 的要求產生這組 ID。產生參考號碼的要求會包含金額和交易說明。
下圖說明系統如何產生並傳送參考號碼給客戶。
產生參考編號流程
以下列出這些物件及其代表的意義:
- 使用者:這是指想透過這個付款方式付費的使用者。
- Google UI:使用者進行購買交易的介面。可能透過網頁或應用程式。
- Google 伺服器:Google 的後端伺服器,會要求產生參考號碼,並為使用者建立付款操作說明。
- 付款整合商伺服器:付款整合商的後端伺服器,用於追蹤付款詳情並產生參考號碼。
此流程由想要使用此現金付款方式的使用者開始。
- 使用者存取 Google 使用者介面,以傳送參考號碼的要求。
- Google UI 傳送訊息給 Google 伺服器,需要參考編號 (
getReferenceNumber
)。 - Google 伺服器要求付款整合商伺服器產生參考號碼 (
generateReferenceNumber
)。 - 付款整合商伺服器會產生參考編號,並傳送至 Google 伺服器。
- Google 伺服器會建立付款指示及參考編號。然後將這些資訊傳送到 Google 使用者介面。
- Google 使用者介面會將這些指示和參考編號傳送給使用者。
參考編號的附註
參考號碼只能支付一次,而且可以透過取消參考號碼流程取消。此外,參考編號必須為英數字元,且必須支援多種顯示格式。
除了顯示參考號碼之外,Google 的使用者介面也可選擇呈現編號 128 格式 (條碼格式) 的參考編號。可要求支援其他條碼格式。
付款參考號碼
使用者可在便利商店、資訊站或銀行中使用這組參考編號,識別使用者要支付的購買交易費用。整合商應讓使用者在付款前顯示購買金額、日期和交易說明,藉此確認購買交易是否已經支付。
使用者選擇付款後,必須付清款項,而且只需付款一次。此 API 不支援以單一參考號碼支付或支付的款項。也無法對單一參考號碼進行多次付款。
使用者付款後,整合商必須立即向 Google 通知 Google 已透過 referenceNumberPaidNotification
方法支付這個參考編號。透過在使用者實際付款後的幾秒內呼叫這個方法,整合商可讓使用者快速收到商品。(如果網路停止運作,這個呼叫可加入佇列)。
付款後,參考編號和金額會列於 T+2 日寄出的匯款對帳單。
以下是參考編號付款的序列圖表。
付款參考編號流程
圖中的物件代表以下內容:
- 使用者:這是指想透過這個付款方式付費的使用者。
- 便利商店:使用者以參考編號和提供的操作說明 (例如便利商店) 付款。
- 付款整合商伺服器:付款整合商的後端伺服器,用於追蹤付款詳情。
- Google 伺服器:Google 的後端伺服器,會要求產生參考號碼,並為使用者建立付款操作說明。
此流程由使用者前往便利商店,以便根據他們提供的指示付款。
- 使用者前往便利商店付款。
- 交易完成後,便利商店會通知付款整合商。
- 付款整合商伺服器傳送成功訊息至便利商店。
- 便利商店表示交易成功給使用者,商品很快就會送達使用者。
- 付款整合商伺服器傳送訊息給 Google 的伺服器,告知已付款參考編號 (
referenceNumberPaidNotification
)。這個步驟不得封鎖步驟 4。 - Google 伺服器會回應「付款整合商伺服器」成功訊息。
取消參考編號
Google 可取消參考號碼。如果 Google 取消參考編號,系統會呼叫 cancelReferenceNumber
方法。成功傳回該號碼後,無法支付該參考號碼的款項,整合商也必須拒絕支付該號碼的款項。呼叫成功後,日後對 referenceNumberPaidNotification
的所有呼叫都會失敗。
如果付款程序已開始,例如使用者已在資訊站中輸入參考號碼,但尚未付款,整合商應傳回包含 USER_ACTION_IN_PROGRESS
的 ErrorResponse 回應代碼。
下一步:匯款流程