本頁面由 Cloud Translation API 翻譯而成。

現金 FOP (AKA 參考編號 API) 指南

以下列舉幾個應考量的重要用途，以及實作現金付款方式時所需的指南和 API。

用途

Reference Number API 有幾個用途。本指南將討論兩種用途，並逐步引導您完成導入程序。

現金 - 使用者在實體店面以現金付款。
VAN - 使用者匯款至虛擬帳號。

現金

使用者可以在實體店面 (例如便利商店) 以現金支付 Google 產品/服務。為識別交易，使用者會產生一組參考號碼，供商家前往商店付款。此外，Google 還會顯示如何完成購買程序的操作說明。在理想情況下，整合商會在使用者完成購買流程後立即通知 Google，讓 Google 能提供產品。

Google 聯絡窗口會請您提供一般付款指示範例。請與您的 Google 聯絡人共同改善及修正訊息內容。

Google 提供的使用者體驗是指客戶訂購的商品在離開店面時就會送達。Google 預計客戶付款參考號碼後，會在三分鐘內收到 Google 的 ReferenceNumberPaidNotification。傳送 ReferenceNumberpaidNotification 後，整合商就無法撤銷交易。

VAN

使用者可以透過銀行帳戶支付商品費用。Google 將向整合商索取虛擬帳號，並向使用者顯示這組號碼和操作說明。使用者接下來需要複製號碼，並在銀行申請中輸入這個號碼，以及轉帳金額。

整合商必須確認匯款金額是否與 referenceNumberGeneration 要求金額相符，然後通知 Google 已支付參考號碼。

一旦 Google 收到 ReferenceNumberPaidNotification，Google 就會交付產品，整合商也無法撤銷交易。

在伺服器和 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 的 API 後，即可開始匯款。所有 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 對應項目。這個欄位會顯示整合服務供應商應付的淨額 (以 micros 為單位)。此外，訊息中的貨幣和類型會顯示在此訊息中，帳單週期分別代表最早和最新的交易日的 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"
}

現金 FOP (AKA 參考編號 API) 指南 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

用途

現金

VAN

在伺服器和 Google 伺服器之間傳送訊息

遵循冪等行為

重要性說明

如何導入冪等性

使用付款整合商帳戶 ID (PIAID)

用於整合的 API

產生參考號碼

要求 JSON

回應 JSON

Java 範例

取消參考號碼

要求 JSON

回應 JSON

referenceNumberPaidNotification

要求 JSON

回應 JSON

實作匯款

remittanceStatementNotification

要求 JSON

對帳 (remittanceStatementDetails)

要求網址

要求主體範例

acceptRemittanceStatement和acceptRemittanceStatementWithModifications

要求「acceptRemittanceStatement」的網址

要求主體範例

回應範例

acceptRemittanceStatementWithModifications 的請求網址

要求主體範例

回應範例

現金 FOP (AKA 參考編號 API) 指南

`referenceNumberPaidNotification`

`remittanceStatementNotification`

對帳 (`remittanceStatementDetails`)

`acceptRemittanceStatement`和`acceptRemittanceStatementWithModifications`

要求「`acceptRemittanceStatement`」的網址

`acceptRemittanceStatementWithModifications` 的請求網址