為儲存和刪除項目使用回呼

本指南說明如何透過 Google Pay API for Passes 使用回呼。每當使用者儲存及刪除項目時，Google 都會在預先設定的類別層級 HTTPS 端點上，透過簽名和使用者儲存/刪除項目的相關資料回呼合作夥伴。

先決條件

在開始之前，請先詳閱以下先決條件：

  • 設定負責處理 POST 要求的 HTTPS 端點。請注意，這個端點必須設為公開端點。
  • 透過程式按類別更新回呼端點。請參閱 REST API 說明文件中 callbackOptions 屬性 (按類別) 的相關說明。
  • (建議) 使用 Tink 程式庫驗證簽名。

執行回呼

每當使用者儲存或刪除物件時，Google 都會對商家進行回呼，並透過各類別網址提供儲存或刪除作業的詳細資料。商家必須先運用公開金鑰驗證訊息的真實性，一旦回呼作業能夠驗證訊息，即可將回呼用於下游作業。

驗證簽名

導入 HTTPS 端點時，建議您選用 Tink 程式庫驗證訊息簽名。Tink 程式庫提供 PaymentMethodTokenRecipient。這項公用程式可自動驗證簽名，並在驗證成功時傳回訊息的實際內容。

以下範例說明如何透過 Tink 程式庫導入 PaymentMethodTokenRecipient：

private static final String PUBLIC_KEY_URL = "https://pay.google.com/gp/m/issuer/keys". // Public key URL provided by Google.
private static final String SENDER_ID = "GooglePayPasses". // Constant.

private static final String RECIPIENT_ID = "ISSUER_ID". // Replace ISSUER_ID with your issuer id.

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());
      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) {
       // …
    }
}

訊息格式規定

訊息格式為 JSON 經過序列化而產生的字串，當中包含以下屬性：

識別碼 說明
classId

完全符合規定的類別 ID，所用格式如下：


<issuer_id.class_id>
objectId

完全符合規定的物件 ID，所用格式如下：


<issuer_id.object_id>
expTimeMillis 自紀元起算的到期時間 (以毫秒為單位)。到期時間屆滿之後，系統就會將訊息視為無效。
eventType 可以是代表刪除的「del」或代表儲存的「save」。
nonce 隨機值，可用於追蹤任何重複的訊息傳送作業。

處理 Google 伺服器發出的要求

傳送至您回呼端點的要求包含多個欄位，以下列出要求標頭的主要欄位：

  • User-Agent：Google-Valuables
  • Content-Type: application/json

請為您的伺服器選用合適的設定，以免伺服器拒絕要求。舉例來說，您可能需要在 robots.txt 中設定下列值：

User-agent: Google-Valuables
Disallow:

重試

回呼會儘可能履行您的要求。如果發生暫時性失敗，Google 會持續傳送訊息三天。三天之後，系統會捨棄該則訊息，日後也不會再重試這項作業。

重複傳送訊息

在某些情況下，系統可能會重複傳送訊息。因此，建議您使用 nonce 來排除重複傳送的情形。