此页面由 Cloud Translation API 翻译。

现金 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 将提供产品，并且集成商无法撤销该交易。

在您的服务器和 Google 服务器之间发送消息

在您的服务器和 Google 服务器之间发送消息时（或者反过来），请遵守以下准则。

传入请求 - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

外发回复 - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google 请求 - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google 回复 - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

此处提供了一个 Java 语言的 PGP 库和示例，其中展示了如何处理请求和响应。

遵循幂等行为

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

重要意义

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

实现汇款

为特定 FOP 集成 API 后，您就可以进行汇款了。所有付款方式的汇款都是一样的。

`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 请求时提供分页的事件列表。如果总交易次数超过 1,000，应多次调用 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（即 Reference Number API）指南

使用场景

现金

VAN

在您的服务器和 Google 服务器之间发送消息

遵循幂等行为

重要意义

如何实现幂等性

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

要集成的 API

生成参考号

请求 JSON

响应 JSON

Java 示例

取消参考号

请求 JSON

响应 JSON

referenceNumberPaidNotification

请求 JSON

响应 JSON

实现汇款

remittanceStatementNotification

请求 JSON

对账 (remittanceStatementDetails)

请求网址

示例请求正文

acceptRemittanceStatement和acceptRemittanceStatementWithModifications

acceptRemittanceStatement 的请求网址

示例请求正文

响应示例

acceptRemittanceStatementWithModifications 的请求网址

示例请求正文

响应示例

`referenceNumberPaidNotification`

`remittanceStatementNotification`

对账 (`remittanceStatementDetails`)

`acceptRemittanceStatement`和`acceptRemittanceStatementWithModifications`

`acceptRemittanceStatement` 的请求网址

`acceptRemittanceStatementWithModifications` 的请求网址