콜백 추가 및 삭제
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 가이드에서는 Google Wallet API에서 콜백을 사용하는 방법을 설명합니다. 사용자가
패스가 생성되거나 삭제되면 Google은
지정할 수 있습니다
이 콜백은 클래스별로 다르며 데이터를 포함합니다.
이벤트 정보(예: 클래스, 객체, 이벤트 유형)
이는 다음을 수행하는 데 사용할 수 있습니다.
사용자 추가 및 삭제 발생 횟수를 추적합니다. 대상
예를 들어 콜백을 통해 분석 이벤트로
프로모션 이벤트 중 고객 참여도를 추적할 수 있습니다.
기본 요건
시작하기 전에 다음 기본 요건을 검토하세요.
-
POST 요청을 처리하는 HTTPS 엔드포인트를 구축합니다. 이 엔드포인트에
공개될 수 있어야 합니다
-
각 클래스의 콜백 엔드포인트를 프로그래매틱 방식으로 업데이트합니다. 자세한 내용은
callbackOptions 드림
속성을 정의하는 데 사용됩니다.
- 권장: Tink 라이브러리를 사용하여 서명을 확인합니다.
콜백 구현
사용자가 서버에서 추가 또는 삭제할 때마다
객체
Google은
클래스당
URL입니다. 판매자는 먼저 공개 키를 사용하여
확인할 수 있습니다. 콜백이 메시지를 확인한 후 콜백을 사용하여
사용할 수 있습니다
서명 확인
Tink 라이브러리를 사용하여 메시지 서명을 확인하는 것이 좋습니다.
HTTPS 엔드포인트를 구현할 때 생성됩니다 이
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
}
}
메시지 형식은 다음과 같은 문자열로 직렬화된 JSON입니다.
속성:
| 식별자 |
설명 |
|---|
classId |
정규화된 클래스 ID입니다. 다음 형식을 사용합니다.
<issuer_id.class_id>
|
objectId |
정규화된 객체 ID입니다. 다음 형식을 사용합니다.
<issuer_id.object_id>
|
expTimeMillis |
EPOCH 이후의 만료 시간(밀리초)입니다. 만료 시간이 지나면
유효하지 않은 것으로 간주해야 합니다.
|
eventType |
다음 경우 del 또는 save일 수 있습니다.
DELETE 및 SAVE.
|
|
nonce |
중복 전송을 추적하기 위한 nonce입니다. |
Google 서버의 요청 처리
다음은 요청 헤더에 포함된 키 필드 목록에
콜백 엔드포인트로 전송됩니다.
- 사용자-에이전트:
Googlebot
- 콘텐츠-유형:
application/json
요청을 거부하지 않도록 서버를 구성합니다. 방법은 다음과 같습니다.
robots.txt에서 다음을 설정합니다.
User-agent: Googlebot
Disallow:
재시도
콜백은 최선의 방식으로 실행됩니다. Google에서 일반적인 재시도 전략을 사용합니다.
콜백 엔드포인트가 응답하지 않거나
중단하고 시도를 단계적으로 중단합니다.
중복 전송
경우에 따라 중복 전송이 발생할 수 있습니다. 이때
nonce하여 중복 데이터를 삭제합니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 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."]]
