本指南介绍了如何通过 Google Wallet API 使用回调。创建或删除卡券时,Google 可以对您选择的 HTTPS 端点执行回调。 此回调特定于传递,包含有关事件的数据,例如 externalPassId 和事件类型。这可用于跟踪发生的用户添加和删除次数。例如,您可以将回调配置为将事件发送到分析应用,以跟踪促销活动期间的客户互动情况。
前提条件
在开始之前,请查看以下前提条件:
- 设置一个用于处理 POST 请求的 HTTPS 端点。此端点需要公开提供。
-
以编程方式更新 issuer 的回调端点网址。请在 REST API 中查看发卡机构的
callbackOptions
属性。 - 推荐:使用 Tink 库来验证签名。
实现回调
针对用户对卡券执行的每次添加或删除操作,Google 都会使用发卡机构回调网址中的添加或删除操作详情,对商家进行回调。商家需要先使用公钥来验证消息的真实性。回调验证消息后,便可将其用于下游操作。
验证签名
我们建议您在实现 HTTPS 端点时使用 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 } }
预期的消息格式
消息格式是序列化为具有以下属性的字符串的 JSON:
标识符 | 说明 |
---|---|
externalPassId |
完全限定外部卡券 ID。使用以下格式: <issuer_id.external_pass_id> |
expTimeMillis |
到期时间(以自纪元以来的毫秒数表示)。到期时间过后,需要将消息视为无效。 |
eventType |
对于 DELETE 和 SAVE ,可以是 del 或 save 。 |
nonce |
用于跟踪任何重复递送的 Nonce。 |
处理来自 Google 服务器的请求
下面列出了发送到回调端点的请求标头中的关键字段:
- 用户代理:
Googlebot
- 内容类型:
application/json
配置服务器,使其不会拒绝请求。为此,您可以在 robots.txt
中进行以下设置:
User-agent: Googlebot Disallow:
重试
我们会尽最大努力进行回调。Google 会尝试两次解释暂时性故障。尝试两次后,Google 会删除相应消息,并且不会尝试重新发送。
重复递送
在某些情况下,可能会出现重复提交的情况。我们建议您使用 nonce
进行去重处理。