コールバックの追加と削除
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
このガイドでは、Google Wallet API でのコールバックの使用方法について説明します。特定の
作成されたか削除された場合、Google は HTTPS へのコールバックを
任意のエンドポイントを使用できます。
このコールバックはクラス固有で、データが含まれます。
クラス、オブジェクト、イベントタイプなど、イベントに関する情報を確認できます。
これを使用して
ユーザーの追加数と削除数を追跡できます。対象
たとえば、イベントをアナリティクスに送信するようにコールバックを構成し、
プロモーション イベント中の顧客エンゲージメントをトラッキングする。
前提条件
始める前に、次の前提条件を満たしていることを確認してください。
-
POST リクエストを処理する HTTPS エンドポイントを起動します。このエンドポイントには、
公開する予定です。
-
各クラスのコールバック エンドポイントをプログラムで更新します。詳しくは、
callbackOptions
クラスごとにプロパティを定義する必要があります。
- 推奨: Tink ライブラリを使用して署名を検証します。
コールバックを実装する
ユーザーが Compute Engine インスタンスに対して
オブジェクト
を受け取ると、Google は販売者にコールバックで、
クラス
URL を入力します。販売者は、最初に公開鍵を使用して、
表示されます。コールバックがメッセージを確認したら、
下流のオペレーションに使用できます
署名の検証
Tink ライブラリを使用して、メールの署名を検証することをおすすめします。
実装時に必要になる場合があります「
Tink ライブラリ
PaymentMethodTokenRecipient というユーティリティにより、
署名を自動的に検証し、応答なしで実際のメッセージを
確認しました。
次の例は、Tink ライブラリを使用して実装する方法を示しています。
PaymentMethodTokenRecipient:
import java.io.IOException;
import javax.servlet.http.*;
import com.google.common.io.CharStreams;
import com.google.crypto.tink.apps.paymentmethodtoken.*;
// Replace ISSUER_ID with your issuer id
private static final String RECIPIENT_ID = "ISSUER_ID";
private static final String PUBLIC_KEY_URL = "https://pay.google.com/gp/m/issuer/keys";
private static final String SENDER_ID = "GooglePayPasses";
private static final String PROTOCOL = "ECv2SigningOnly";
private static final GooglePaymentsPublicKeysManager keysManager = new GooglePaymentsPublicKeysManager.Builder()
.setKeysUrl(PUBLIC_KEY_URL)
.build();
public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
try {
// Extract signed message with signature from POST request body.
String signedMessage = CharStreams.toString(request.getReader());
PaymentMethodTokenRecipient recipient =
new PaymentMethodTokenRecipient.Builder()
.protocolVersion(PROTOCOL)
.fetchSenderVerifyingKeysWith(keysManager)
.senderId(SENDER_ID)
.recipientId(RECIPIENT_ID)
.build();
String serializedJsonMessage = recipient.unseal(signedMessage);
// Use serializedJsonMessage to extract the details
} catch (Exception e) {
// Handle the error
}
}
メッセージ形式は、
プロパティ:
| 識別子 |
説明 |
|---|
classId |
完全修飾クラス ID。次の形式を使用します。
<issuer_id.class_id>
|
objectId |
完全修飾のオブジェクト ID。次の形式を使用します。
<issuer_id.object_id>
|
expTimeMillis |
エポックからのミリ秒単位の有効期限です。有効期限が切れた後は、
メッセージは無効とみなす必要があります。
|
eventType |
del または save のいずれかになります。
DELETE と SAVE。
|
|
nonce |
重複配信を追跡するノンス。 |
Google サーバーからのリクエストの処理
リクエストのヘッダーに含まれる主要なフィールドのリストは次のとおりです。
コールバック エンドポイントに送信されます。
- ユーザー エージェント:
Googlebot
- コンテンツ タイプ:
application/json
リクエストを拒否しないようにサーバーを構成します。そのためには、
robots.txt で次のように設定します。
User-agent: Googlebot
Disallow:
再試行数
コールバックはベスト エフォート方式です。Google は一般的な再試行戦略を使用します。
コールバック・エンドポイントが応答しない場合や
障害に適切に対応し 再試行を無事に阻止します
重複配信
重複配信が発生する場合があります。Google Cloud コンソールの
nonce を使用して重複を排除します。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-08-29 UTC。
[null,null,["最終更新日 2025-08-29 UTC。"],[[["\u003cp\u003eGoogle Wallet API callbacks allow you to receive real-time updates when passes are created or deleted by users.\u003c/p\u003e\n"],["\u003cp\u003eThese callbacks send data to your HTTPS endpoint, enabling you to track user engagement and perform custom actions.\u003c/p\u003e\n"],["\u003cp\u003eYou need to set up an HTTPS endpoint, update the callback endpoint for each class, and verify the signature using a library like Tink.\u003c/p\u003e\n"],["\u003cp\u003eThe callback message contains information about the event, such as class ID, object ID, event type, and a nonce to handle duplicates.\u003c/p\u003e\n"],["\u003cp\u003eCallbacks are on a best-effort basis with retry strategies, and you should handle potential duplicate deliveries using the nonce.\u003c/p\u003e\n"]]],["Google Wallet API uses callbacks to notify merchants of pass creation or deletion events. Merchants must set up a public HTTPS endpoint to receive these POST requests and update the callback endpoint per class via the API. Callbacks include class, object, and event type data (save or delete). Merchants should use the Tink library to verify message signatures using public keys, then utilize the JSON payload to process the event data. Google sends the requests with the header user-agent `Googlebot`.\n"],null,["# Add and delete callbacks\n\nThis guide explains how to use callbacks with the Google Wallet API. When a\npass is created or deleted, Google can perform a callback to an HTTPS\nendpoint of your choosing.\n\nThis callback is class-specific, and includes data\nabout the event such as the class, object, and event type.\n\nThis can be used to\nkeep track of the number of user adds and deletions that occur. For\nexample, callbacks can be configured to send events to an analytics\napplication to track customer engagement during promotional events.\n\nPrerequisites\n-------------\n\nBefore you start, review the following prerequisites:\n\n- Stand up an HTTPS endpoint that handles POST requests. This endpoint needs to be publicly available.\n- Programmatically update the callback endpoint for each class. See the [`callbackOptions`](/wallet/retail/gift-cards/rest/v1/CallbackOptions) property by class in the REST API.\n- Recommended: Use the [Tink](https://developers.google.com/tink) library to verify the signatures.\n\nImplement callbacks\n-------------------\n\n\nFor every add or delete performed by the user on an\n\nan object\n\n, Google makes callbacks to the merchants with details about the add or delete on a\n\nper-class\n\nURL. Merchants need to first use the Public Keys to verify the authenticity of\nthe message. After the callbacks verify the message, the callbacks can be used\nfor downstream operations.\n\nVerify the signature\n--------------------\n\n\nWe recommend that you use the Tink library to verify the message signature\nwhen you implement your HTTPS endpoint. The\n[Tink library](https://github.com/google/tink)\nprovides `PaymentMethodTokenRecipient`, a utility that\nautomatically verifies the signature and returns the actual message upon\nsuccessful verification.\n\n\nThe following example shows how to use the Tink library to implement\n`PaymentMethodTokenRecipient`: \n\n```python\nimport java.io.IOException;\nimport javax.servlet.http.*;\nimport com.google.common.io.CharStreams;\nimport com.google.crypto.tink.apps.paymentmethodtoken.*;\n\n// Replace ISSUER_ID with your issuer id\nprivate static final String RECIPIENT_ID = \"\u003cvar translate=\"no\"\u003eISSUER_ID\u003c/var\u003e\";\n\nprivate static final String PUBLIC_KEY_URL = \"https://pay.google.com/gp/m/issuer/keys\";\nprivate static final String SENDER_ID = \"GooglePayPasses\";\nprivate static final String PROTOCOL = \"ECv2SigningOnly\";\n\nprivate static final GooglePaymentsPublicKeysManager keysManager = new GooglePaymentsPublicKeysManager.Builder()\n .setKeysUrl(PUBLIC_KEY_URL)\n .build();\n\npublic void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {\n try {\n // Extract signed message with signature from POST request body.\n String signedMessage = CharStreams.toString(request.getReader());\n PaymentMethodTokenRecipient recipient =\n new PaymentMethodTokenRecipient.Builder()\n .protocolVersion(PROTOCOL)\n .fetchSenderVerifyingKeysWith(keysManager)\n .senderId(SENDER_ID)\n .recipientId(RECIPIENT_ID)\n .build();\n\n String serializedJsonMessage = recipient.unseal(signedMessage);\n\n // Use serializedJsonMessage to extract the details\n } catch (Exception e) {\n // Handle the error\n }\n}\n```\n\nExpected message format\n-----------------------\n\n\nThe message format is JSON that's serialized into a string with the following\nproperties:\n\n| Identifier | Description |\n|-----------------|-----------------------------------------------------------------------------------------------------------------|\n| `classId` | Fully qualified class ID. Uses the following format: ``` \u003cissuer_id.class_id\u003e ``` |\n| `objectId` | Fully qualified object ID. Uses the following format: ``` \u003cissuer_id.object_id\u003e ``` |\n| `expTimeMillis` | Expiration time in milliseconds since EPOCH. After the expiration time, the message needs to be deemed invalid. |\n| `eventType` | Can be either `del` or `save` for `DELETE` and `SAVE`. |\n| `nonce` | Nonce to track any duplicate deliveries. |\n\n### Handle the request from a Google server\n\n\nThe following is a list of the key fields in the header of the request that's\nsent to your callback endpoint:\n\n- User-Agent: `Googlebot`\n- Content-Type: `application/json`\n\n\nConfigure your server so that it doesn't reject the request. To do so, you can\nset the following in `robots.txt`: \n\n```\nUser-agent: Googlebot\nDisallow:\n```\n\n### Retries\n\n\nCallbacks are on a best-effort basis. Google will use common retry strategies\nto be resilient in cases where the callback endpoint is not responding or has an\nintermittent outage and will gracefully back off attempts.\n\n### Duplicate deliveries\n\n\nThere might be duplicate deliveries in some cases. We recommend that you use\n`nonce` to dedupe them."]]
