トークンのライフサイクル管理に関する通知

概要

今後のトークンライフサイクル管理（LCM）通知は、Google Pay Online API から、元のトランザクション時に指定された tokenUpdateUrl に送信されます。トークンが無効化または削除された場合に送信されます。また、配信に失敗した場合は再試行が行われ、ベストエフォート方式で送信されます。ユーザーが Google ウォレットからカードを削除した場合の LCM フローの例を次に示します。

MerchantTokenUpdateNotificationRequest

Google Pay Online API からの HTTP POST メッセージには、暗号化されたペイロードをカプセル化した JSON 本文が含まれています。ペイロードは、共有公開暗号鍵で暗号化され、Google の秘密鍵で署名されます。秘密暗号鍵で復号し、 Google's のルート署名鍵で検証できます。この暗号化されたペイロードラッパーの形式は、 PaymentMethodTokenとして受け取るものと同じです。同じライブラリを使用して、この LCM 通知を復号できます。暗号化されたペイロード内には、ここに記載されている MerchantTokenUpdateNotificationRequest オブジェクトがあります。

プロパティ	タイプ	必須	説明
`messageId`	文字列	必須	メッセージの重複排除とデバッグを目的とした、この通知の一意の ID。この通知が正常に配信されなかった場合、今後の再試行でも同じ ID が使用されます。
`targetNotificationUrl`	文字列	必須	この通知の宛先 URL。この URL が、Google Pay からトークン LCM 通知を受信するエンドポイントであることを確認する必要があります。注: URL が所有していない場合や間違っている場合は、HTTP 400 で応答する必要があります。
`timestamp`	文字列	必須	この通知が最初に作成されたときのタイムスタンプ。今後の再試行でも同じ ID が使用されます。同じトークン ID の通知を複数受け取った場合は、タイムスタンプが最も新しい通知のみが正確と見なされます。
`apiVersion`	int	必須	API のメジャーバージョン。
`apiVersionMinor`	int	必須	API のマイナーバージョン。
`merchantTokenId`	文字列	必須	更新された販売者トークン ID。これは、ユーザーが Google Pay フローを完了したときに最初に返された ID です。これは、暗号化されたペイロード内のフィールドで、 `Card` オブジェクト。
`cardUpdateInfo`	CardUpdateInfo	必須	トークンの更新情報が含まれます。

CardUpdateInfo

プロパティタイプ必須説明

プロパティ	タイプ	必須	説明
`fpanSuffix`	文字列	条件文	ユーザーが基盤となる Funding Primary Account Number（FPAN）を識別できるようにするための説明。 FPAN の最後の 4 文字を含む 4 桁の文字列です。存在する場合、トークンの状態はアクティブであると想定できます。変更がない場合は存在しません。
`tokenState`	文字列（列挙型）	条件文	最初のトランザクションまたは以前の通知から変更された場合のトークンの新しい状態。変更がない場合は存在しません。有効な値は `DISABLED` です。

fpanSuffix

文字列

条件文

ユーザーが基盤となる Funding Primary Account Number（FPAN）を識別できるようにするための説明。 FPAN の最後の 4 文字を含む 4 桁の文字列です。

存在する場合、トークンの状態はアクティブであると想定できます。

変更がない場合は存在しません。

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

復号された 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 を呼び出し、エンドポイント URL を tokenUpdateUrl フィールドに入力して、テストトランザクションを完了します。 *TransactionInfo
注: トランザクションを完了してテストモードで通知をトリガーするには、ペイシートの [続行] または [お支払い] ボタンをクリックする必要があります。
Google のサービスがトークン LCM 通知をエンドポイントに送信します。
秘密鍵を使用して通知を復号できることを確認します。テストモードでは、リクエスト内のトークンに関係なく、この通知ではカード番号の下 4 桁が常に「1234」に変更され、 "tokenState": "DISABLED"が含まれます。