现金 FOP（即 Reference Number API）指南

以下是一些需要考虑的重要用例，以及实现现金付款方式所需的准则和 API。

使用场景

Reference Number API 有多种用途。本指南将讨论两种使用场景并逐步引导您完成实现。

现金 - 用户在实体店使用现金付款。
VAN - 用户向虚拟账号转账。

现金

用户可以在 Google 购物时，在实体店（例如便利店）使用现金付款。为了识别交易，用户会生成一个参考号，用于前往商店付款。此外，Google 还会向用户显示有关如何完成购买的说明。理想情况下，集成商会在用户完成购买后立即通知 Google，以便 Google 交付产品。

您的 Google 联系人会请您提供典型付款说明的示例。您需要与您的 Google 联系人合作，对广告内容进行优化和优化。

Google 希望提供的用户体验是，当客户离开商店时，订单会自动送达。Google 预计会在客户支付参考号后的三分钟内收到 ReferenceNumberPaidNotification。发送 ReferenceNumberPaidNotification 后，集成商将无法撤销交易。

VAN

用户可以使用自己的银行账户为商品付款。Google 会向集成商请求一个虚拟账号，并向用户显示该号码和说明。然后，用户需要复制该号码，并在转账金额之外将其输入到银行应用中。

集成商需要验证转出的金额是否与 referenceNumberGeneration 请求金额相符，然后通知 Google 该参考号已支付。

一旦收到 ReferenceNumberPaidNotification，Google 将提供产品，并且集成商无法撤销该交易。

Sending messages between your servers and Google's servers

When sending messages between your servers and Google’s servers, or the other way around, please do so according to these guidelines.

Incoming request - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Outgoing response - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google request - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google response - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Here is a PGP library and sample in java that shows handling requests and responses.

遵循幂等行为

幂等性意味着您不应尝试重新处理任何已成功处理的请求（例如付款）。应改为报告成功处理的响应。

重要意义

Google 可能会重试某些请求，以确保我们端的状态与供应商端的状态相同。系统不应认为这是另一笔交易。因此，幂等性非常重要。这意味着集成商不应重新处理已成功处理的请求。在这种情况下，应改为发送上一个响应。

如何实现幂等性

如果 Google 发送重试，请求 ID 将相同，内容将相同，但时间戳不同。使用您之前发送的相同回复进行回复。如果您的第一个响应是 200 (Success)，那么 Google 会认为相同的响应只是时间戳不同。

如果之前的响应为错误（400 或 500 等），则应将该请求作为新请求进行处理，并再次检查。如果您的服务器第一次发生故障，那么通过重试，您可以再次有机会成功处理请求，这样做会很有帮助。

如需了解详情，请参阅此详细指南。

使用付款集成商账号 ID (PIAID)

与 Google 集成可能需要与 Google 的不同业务实体集成。例如，Google Play 是一个实体，一个是 YouTube，还有另一个是 Google Ads。这些配置会涉及不同的商家账号，分别表示这些配置。

对于从 Google 中的每个实体到每个商家账号的映射，Google 提供了付款集成商账号 ID (PIAID)。如需查看现金 FOP API 的示例，请参阅 generateReferenceNumber。以下是使用此映射的示例。

对于从 Google 中的每个实体到每个商家账号的映射，Google 提供了付款集成商账号 ID (PIAID)。如需查看使用 Cash 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/AcceptRemittanceCondition

您需要集成上述所有 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"
}

Implement remittance

Once you have integrated the APIs for your particular FOP, you are ready for remittance. Remittance works the same across all FOPs.

`remittanceStatementNotification`

Two days after a transaction, Google will send a remittanceStatementNotification containing a summary of the transactions Google recorded that day. A sample notification looks like this, two days after a transaction:

POST https://www.integratordomain.com/v1/remittanceStatementNotification

Request 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",
  }
}

Notice the totalDueByIntegrator mapping. On this line you can see the net amount the Integrator owes (in micros). Also, the date and type of currency appear in this message, with the billing period representing 00:00:00.000 and 23:59:59.999 of the earliest and latest transaction day(s) respectively.

Reconciliation (`remittanceStatementDetails`)

For reconciliation, the integrator will call remittanceStatementDetails to get the list of events included in the remittanceStatementNotification.

Google responds to the remittanceStatementDetails request with a paginated list of events. remittanceStatementDetails should be called multiple times if the number of total transactions is greater than 1000. The requests do not need to be made sequentially, and can be parallelized.

Request URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

Sample request body

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

Here is a short snippet of a larger response, describing two capture events (transactions).

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

See remittanceStatementDetails to learn more.

`acceptRemittanceStatement` and `acceptRemittanceStatementWithModifications`

Integrators should compare these events against the events that they have recorded. If any transactions do not match or transactions are missing, contact Google for further investigation. If all transactions match, and the process fee does not include taxes, call acceptRemittanceStatement. If taxes are inclusive, call acceptRemittanceStatementWithModifications.

The acceptRemittanceStatement method is used when there are no taxes on fees.

If a tax is to be included, call acceptRemittanceStatementWithModifications and define the tax rate. If your tax rate changes, make sure this is updated. After a successful acceptRemittanceStatement, initiate your bank transfer to the Google account.

Request URL for `acceptRemittanceStatement`

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

Sample request body

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

Sample response

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

Request URL for `acceptRemittanceStatementWithModifications`

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

Sample request body

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

Sample response

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}

现金 FOP（即 Reference Number API）指南 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

使用场景

现金

VAN

Sending messages between your servers and Google's servers

遵循幂等行为

重要意义

如何实现幂等性

使用付款集成商账号 ID (PIAID)

要集成的 API

生成参考号

请求 JSON

响应 JSON

Java 示例

取消参考号

请求 JSON

响应 JSON

referenceNumberPaidNotification

请求 JSON

响应 JSON

Implement remittance

remittanceStatementNotification

Request JSON

Reconciliation (remittanceStatementDetails)

Request URL

Sample request body

acceptRemittanceStatement and acceptRemittanceStatementWithModifications

Request URL for acceptRemittanceStatement

Sample request body

Sample response

Request URL for acceptRemittanceStatementWithModifications

Sample request body

Sample response

现金 FOP（即 Reference Number API）指南

`referenceNumberPaidNotification`

`remittanceStatementNotification`

Reconciliation (`remittanceStatementDetails`)

`acceptRemittanceStatement` and `acceptRemittanceStatementWithModifications`

Request URL for `acceptRemittanceStatement`

Request URL for `acceptRemittanceStatementWithModifications`