令牌生命周期管理通知

概览

未来的令牌生命周期管理 (LCM) 通知将从 Google Pay Online API 发送到 tokenUpdateUrl 原始交易时提供的。如果令牌被停用或删除，系统会发送这些通知。系统还会尽力发送这些通知，并在传送失败时进行重试。以下示例展示了用户从 Google 钱包中移除银行卡时的 LCM 流程：

MerchantTokenUpdateNotificationRequest

这是来自 Google Pay Online API 的 HTTP POST 消息，其中包含封装了加密载荷的 JSON 正文。该载荷使用您共享的公共加密密钥进行加密，并使用 Google 的私钥进行签名。您可以使用自己的私有加密密钥进行解密，并使用 Google 的根签名密钥进行验证。这种加密载荷封装容器格式与您可能收到的 PaymentMethodToken 相同。您可以使用相同的库来解密此 LCM 通知。在加密载荷中，有一个 MerchantTokenUpdateNotificationRequest 对象，详情如下。

属性	类型	必要性	说明
`messageId`	字符串	必需	此通知的唯一 ID，用于对消息进行去重和调试。如果此通知未成功传送，则在以后的重试中，此 ID 保持不变。
`targetNotificationUrl`	字符串	必需	此通知的目标网址。您必须确认此网址是您打算从 Google Pay 接收令牌 LCM 通知的端点。注意：如果该网址不属于您或不正确，您必须使用 HTTP 400 进行响应。
`timestamp`	字符串	必需	最初创建此通知时的时间戳。在以后的重试中，此时间戳保持不变。如果您收到同一令牌 ID 的多个通知，则只有具有最新时间戳的通知才被认为是准确的。
`apiVersion`	int	必需	API 主要版本。
`apiVersionMinor`	int	必需	API 次要版本。
`merchantTokenId`	字符串	必需	具有更新的商家令牌 ID。这是用户完成 MIT 的 Google Pay 流程时最初返回的 ID。这是加密载荷中的一个字段，在 `Card` 对象。
`cardUpdateInfo`	CardUpdateInfo	必需	包含令牌的更新。

CardUpdateInfo

属性类型必要性说明

属性	类型	必要性	说明
`fpanSuffix`	字符串	基于条件	帮助用户识别底层资金主账号 (FPAN) 的说明。这是一个四位数字的字符串，包含 FPAN 的最后四个字符。如果存在此字符串，则可以假定令牌状态为有效。如果没有更改，则不会显示此字符串。
`tokenState`	字符串（枚举）	基于条件	令牌的新状态（如果自初始交易或上一个通知以来发生了更改）。如果没有更改，则不会显示此字符串。有效值为 `DISABLED`。

fpanSuffix

字符串

基于条件

帮助用户识别底层资金主账号 (FPAN) 的说明。这是一个四位数字的字符串，包含 FPAN 的最后四个字符。

如果存在此字符串，则可以假定令牌状态为有效。

如果没有更改，则不会显示此字符串。

tokenState

字符串（枚举）

基于条件

令牌的新状态（如果自初始交易或上一个通知以来发生了更改）。

如果没有更改，则不会显示此字符串。

有效值为 DISABLED。

MerchantTokenUpdateNotificationResponse

HTTP 响应代码

HTTP 响应代码	用法
200	通知已成功收到。如需了解其他状态信息，请参阅下表，在响应正文中以 JSON 对象的形式提供。
401	`MerchantTokenUpdateNotificationRequest` 中的 `targetNotificationUrl` 无效。您可以停用此令牌的所有未来通知。
5xx	临时服务器错误。应稍后再次发送通知。
其他	不可重试的错误。不应稍后再次发送通知。

属性类型必要性说明

属性	类型	必要性	说明
`requestMessageId`	字符串	必需	从请求生成的消息 ID。它必须与请求中的消息 ID 匹配，否则系统可能会忽略响应，并停止此令牌的未来通知。
`status`	字符串（枚举）	必需	商家或支付服务提供商 (PSP) 可以返回一个状态，以反映他们的接收情况以及对令牌的使用情况。有效值包括： `SUCCESS` `TOKEN_NOT_IN_USE` `TOKEN_NOT_FOUND`

requestMessageId

字符串

必需

从请求生成的消息 ID。

它必须与请求中的消息 ID 匹配，否则系统可能会忽略响应，并停止此令牌的未来通知。

status

字符串（枚举）

必需

商家或支付服务提供商 (PSP) 可以返回一个状态，以反映他们的接收情况以及对令牌的使用情况。

有效值包括：

SUCCESS
TOKEN_NOT_IN_USE
TOKEN_NOT_FOUND

示例

生命周期通知

通知请求

这是 HTTP POST 请求，其中包含从 Google Pay 发送到您的端点的令牌 LCM 通知。正文是加密载荷。

HTTP 请求

  HTTP POST /token/notification/123
  Host: api.merchant.com
  Content-Type: application/json

  {
    "protocolVersion":"ECv2",
    "signature":"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\u003d\u003d",
    "intermediateSigningKey":{
      "signedKey": "{\"keyExpiration\":\"1542323393147\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw\\u003d\\u003d\"}",
      "signatures": ["MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v"]
    },
    "signedMessage":"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\u003d\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\u003d\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}"
  }

解密的 MerchantTokenUpdateNotificationRequest

  {  // MerchantTokenUpdateNotificationRequest
    "messageId": "ZlxoWhLC3su",
    "targetNotificationUrl":
      "https://api.merchant.com/token/notification/123",
    "timestamp": "2025-03-28T07:53:12.39Z",
    "apiVersion": 1,
    "apiVersionMinor": 0,
    "merchantTokenId": "123",
    "cardUpdateInfo": {
      "tokenState": "DISABLED"
    }
  }

通知响应

  HTTP 200 OK
  Content-Type: application/json

  {  // MerchantTokenUpdateNotificationResponse
    "requestMessageId": "ZlxoWhLC3su",
    "status": "SUCCESS",
  }

使用您的 tokenUpdateUrl 端点进行测试

在 TEST 模式下，Google Pay 会向您的 tokenUpdateUrl 发送令牌 LCM 通知。如需触发此通知，请按以下步骤操作：

通过使用 *TransactionInfo 对象调用 loadPaymentData 来完成测试交易，并使用您的端点网址填充 tokenUpdateUrl 字段
注意：如需在 TEST 模式下完成交易并触发通知，您必须点击付款表单中的继续或付款按钮。
Google 的服务会将令牌 LCM 通知发送到您的端点。
验证您是否可以使用自己的私钥解密通知。请注意，在 TEST 模式下，此通知始终会将银行卡号的最后 4 位数字更改为“1234”，并包含 "tokenState": "DISABLED"，无论请求中的令牌如何。