令牌生命周期管理通知

概览

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

MerchantTokenUpdateNotificationRequest

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

属性	类型	必要性	说明
`messageId`	字符串	必需	相应通知的唯一 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

示例

生命周期通知

通知请求

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

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

Decrypted 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 字段。
注意：如需完成交易并在测试模式下触发通知，您必须点击支付单中的继续或付款按钮。
Google 的服务将向您的端点发送令牌 LCM 通知。
验证您是否可以使用私钥解密通知。请注意，在测试模式下，无论请求中的令牌是什么，此通知始终会将卡号的后 4 位数字更改为“1234”，并包含 "tokenState": "DISABLED"。