以下列出一些需要考量的重要用途，以及實作現金 FOP 的規範和 API。
應用情境
Reference Number API 有多種用途。本指南將討論兩種使用案例，並逐步引導您完成實作程序。
現金
使用者在 Google 上購買商品時，可以在實體商店 (例如便利商店) 以現金付款。為識別交易，使用者將產生一組參考號碼，以便前往商店付款。此外，Google 還會向使用者顯示說明如何完成購買程序的操作說明。最好在使用者完成購買後立即通知 Google，讓 Google 能夠運送產品。
Google 聯絡窗口要求您提供一般付款指示的範本。您將與 Google 聯絡人合作，最佳化調整訊息。
Google 提供的使用者體驗是指，客戶在離開商店後能收到訂購商品。Google 預期在客戶支付參考編號後的三分鐘內，將收到 ReferenceNumberPaidNotification。傳送 ReferenceNumberPaymentNotification 後，整合商就無法撤銷交易。
VAN
使用者可以透過銀行帳戶支付商品費用。Google 會要求整合商提供虛擬帳號，並向使用者顯示號碼和操作說明。使用者接著可以複製號碼，並在轉帳金額時輸入這組號碼，並輸入銀行的應用程式中。
整合商必須確認轉帳金額與 ReferenceNumberGeneration 要求金額相符，然後通知 Google 已支付參考編號。
Google 收到 ReferenceNumberPaidNotification 時，將會收到產品，且整合商無法撤銷交易。
在伺服器和 Google 伺服器之間傳送訊息
在自家伺服器與 Google 伺服器之間收發郵件時，請按照這些指南操作。
傳入要求 - DecryptWithVendorPrivateKey(Base64UrlDecode(request))
傳出回應 - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Google 要求 - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Google 回應 - DecryptWithVendorPrivateKey(Base64UrlDecode(request))
以下是 Java 中的 PGP 程式庫和範例，其中顯示處理要求與回應。
遵循冪等行為
冪等性是指請勿嘗試重新處理已順利處理的任何要求 (例如付款)。請改為回報成功處理的回應。
重要性說明
Google 可能會重試部分要求，確保我們端的狀態與供應商端的狀態相同。您的系統不應認為這是另一筆交易。因此冪等性便相當重要。也就是說，整合商不應該重新處理已順利處理的內容。在這種情況下，系統應改為傳送先前的回應。
如何實作冪等性
如果 Google 傳送重試，要求 ID 將相同，內容也會相同，但時間戳記會有所不同。請使用你先前傳送的相同回覆。如果您的第一則回應是 200 (成功)，Google 會預期相同的回應含有不同的時間戳記。
如果先前的回應是錯誤 (400 或 500 等)，請將該要求視為新的要求來處理，再檢查一次。如果您的伺服器第一次當機，重試時也有助於要求再次成功處理要求。
詳情請參閱這份詳細指南。
使用付款整合商帳戶 ID (PIAID)
與 Google 整合可能需要與 Google 的不同企業實體整合。舉例來說，Google Play 是某實體，另一個是 YouTube，另一個是 Google Ads。這些帳戶會涉及不同的商家帳戶，分別代表各項設定。
針對 Google 內部各實體與各個商家帳戶的對應關係，Google 會提供付款整合商帳戶 ID (PIAID)。如需現金 FOP API 的範例，請參閱 generateReferenceNumber。以下為使用此對應的範例。
針對 Google 內部各實體與各個商家帳戶的對應關係，Google 會提供付款整合商帳戶 ID (PIAID)。如需使用現金 FOP API 的範例，請參閱 generateReferenceNumber。以下為使用此對應的範例。
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"transactionDescription": "Google - Music",
"currencyCode": "USD",
"amount": "2000000"
}
請注意醒目顯示的部分。這裡需要的兩個值是 Google 聯絡窗口和商家帳戶提供的 paymentIntegratorAccountId。
整合商的帳戶可能會因提供服務的國家/地區而異，原因可能是因稅務法規和其他國家/地區而異。在此情況下，系統可能會為每個國家/地區另外產生 PIAID。
要整合的 API
下列 API 會處理參考號碼產生和付款通知。
以下 API 會處理匯款和結算作業。
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AcceptRemittanceStatement，包含修改內容
您必須整合上述所有 API，才能產生參考號碼並與 Google 達成協議。
產生參考編號
當您進行購買交易時，Google 會呼叫 GenerateReferenceNumber。回覆時，請提供交易或帳戶的參考編號，方便我們識別交易或帳戶。預計延遲時間少於 3 秒。
如為現金交易，參考編號的長度上限為 12 個字元。
網址：POST https://[your basepath]/v1/generateReferenceNumber
要求 JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"requestTimestamp": "1561678470395"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"transactionDescription": "Google Play - Tester",
"currencyCode": "USD",
"amount": "10000000"
}
回應 JSON
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Java 範例
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
取消參考編號
Google 可能會選擇取消參考號碼，並避免使用者支付該號碼。舉例來說，如果促銷活動已過期，當您收到這項要求的回應後，必須確認該參考編號無法支付。
如果使用者已啟動付款程序 (例如從銷售點查詢的參考編號查詢)，您的伺服器應在要求主體中以 HTTP 423 回應回應，而 ErrorResponse 以 USER_ACTION_IN_PROGRESS 的狀態回應。
網址：POST https://[your basepath]/v1/cancelReferenceNumber
要求 JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "51e00f16-36ba-4490-b228-0a670d202206",
"requestTimestamp": "1561678947926"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
回應 JSON
{
"responseHeader": {
"responseTimestamp": "1561680406459"
},
"result": "SUCCESS"
}
referenceNumberPaidNotification
當系統接受付款並完成交易後，您的服務需要通知 Google 交易已完成，並將產品交付給使用者。Google 收到這項通知後，預期交易已敲定，且不可保留。
referenceNumberPaidNotification 端點網址：
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
要求 JSON
{
"requestHeader": {
"requestTimestamp": "1561748625577",
"requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
}
},
"paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
"paymentLocation": {
"brandName": "TestMart",
"locationId": "1234"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"paymentTimestamp": "1561748625577"
}
回應 JSON
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
導入匯款
您的特定 FOP 整合完畢後，即可進行匯款。所有付款方式都相同。
remittanceStatementNotification
在交易的兩天後，Google 會傳送 remittanceStatementNotification，其中包含 Google 當天記錄的交易摘要。以下是交易後兩天的通知範例：
POST https://www.integratordomain.com/v1/remittanceStatementNotification
要求 JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-statement-abc",
"requestTimestamp": "1502632800000"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"remittanceStatementSummary": {
"statementDate": "1502607600000",
"billingPeriod": {
"startDate": "1502434800000",
"endDate": "1502521199000",
},
"dateDue": "1503212400000",
"currencyCode": "INR",
"totalDueByIntegrator": "1076000000",
}
}
請注意 totalDueByIntegrator 對應。此行會顯示整合商的淨額 (在「微量」中)。此外，這則訊息中也會顯示貨幣的日期和類型，並分別代表最早和最近交易日的 00:00:00.000 和 23:59:59.999。
對帳 (remittanceStatementDetails)
針對協調作業，整合商會呼叫 remittanceStatementDetails，取得 remittanceStatementNotification 包含的事件清單。
Google 會以分頁式事件清單回應 remittanceStatementDetails 要求。如果交易總數超過 1000，請多次呼叫 remittanceStatementDetails。要求不必依序提出，而且可以平行處理。
要求網址
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
要求主體範例
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
以下是一份大型回應的簡短文字片段，說明兩個擷取事件 (交易)。
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
詳情請參閱 remittanceStatementDetails。
acceptRemittanceStatement和acceptRemittanceStatementWithModifications
整合商應將這些事件與自己記錄的事件進行比較。如果有任何交易不相符，或是缺少交易，請與 Google 聯絡以進行深入調查。如果所有交易都相符，且程序費用不包含稅金，請呼叫 acceptRemittanceStatement。如果含稅，請呼叫 acceptRemittanceStatementWithModifications。
不收取任何費用時，系統會使用 acceptRemittanceStatement 方法。
如果是要納入稅金，請呼叫 acceptRemittanceStatementWithModifications 並定義稅率。如果稅率有所變動，請確認這項資訊已經更新。成功完成 acceptRemittanceStatement 後，請將銀行轉帳作業轉至 Google 帳戶。
要求「acceptRemittanceStatement」的網址
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
要求主體範例
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
回應範例
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
要求「acceptRemittanceStatementWithModifications」的網址
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
要求主體範例
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
回應範例
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}