令牌生命周期管理通知

概览

未来的令牌生命周期管理 (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 通知的端点。
timestamp 字符串 必需

相应通知最初创建时的时间戳。在后续重试中保持不变。

如果您收到同一令牌 ID 的多条通知，则只有时间戳最新的通知才被视为准确。
apiVersion int 必需 API 主要版本。
apiVersionMinor int 必需 API 次要版本。
merchantTokenId 字符串 必需 包含更新的商家令牌 ID。这是用户完成 MIT 的 Google Pay 流程时最初返回的 ID。这是加密载荷中的一个字段，在 Card 对象。
cardUpdateInfo CardUpdateInfo 必需 包含令牌的更新。

CardUpdateInfo

属性 类型 必要性 说明
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

示例

生命周期通知

通知请求

这是包含令牌 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"。