權杖生命週期管理通知

總覽

日後，Google Pay 線上 API 會將權杖生命週期管理 (LCM) 通知傳送至原始交易時提供的 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。

否則系統可能會忽略回覆，並停止傳送這個權杖的後續通知。
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\"}"
  }

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 端點進行測試

在測試模式下，Google Pay 會將權杖 LCM 通知傳送至 tokenUpdateUrl。 如要觸發這項操作，請按照下列步驟操作：

  • 呼叫 loadPaymentData 並使用 *TransactionInfo 物件，在 tokenUpdateUrl 欄位中填入端點網址，即可完成測試交易。
  • Google 服務會將權杖 LCM 通知傳送到您的端點。
  • 確認您可以使用私密金鑰解密通知。請注意，在測試模式中，無論要求中的權杖為何，這項通知一律會將卡號末 4 碼變更為「1234」，並包含 "tokenState": "DISABLED"。