Google Pay API for Passes 的 Web API 參考資料

Google Pay API for Passes 可讓您的使用者將網路上的物件儲存至 Google Pay。使用者可直接透過您的網站儲存自己的卡片。

本參考資料將詳細說明用來呈現 Google Pay API for Passes 按鈕的 HTML 元素 g:savetoandroidpay,以及用來向 Google 說明網路服務的 JSON Web Token

Google Pay API for Passes JavaScript

如要自動剖析負載中的 g:savetoandroidpay HTML 標記,請加入標準 JavaScript。

<script src="https://apis.google.com/js/platform.js" type="text/javascript"></script>

如果是 AJAX 應用程式,以及如要明確呈現 Google Pay API for Passes 按鈕,請加入 "parsetags": "explicit" 參數。

<script src="https://apis.google.com/js/platform.js" type="text/javascript">
  {"parsetags": "explicit"}
</script>

g:savetoandroidpay HTML 標記

g:savetoandroidpay 命名空間標記可用來定義 [儲存至 Google Pay] 按鈕的位置和各種屬性。如要轉譯 HTML 和 JWT 伺服器端,請使用這個標記。

<g:savetoandroidpay jwt="JWT" onsuccess="successHandler" onfailure="failureHandler" />
欄位 類型 必填 說明
height 字串 按鈕的顯示高度。可用的值為:small (高 30px) 和 standard (高 38px)。height 的預設值為 small。如要採用不同 height 設定的按鈕範例,請參閱 Google Pay API for Passes 按鈕的相關說明。
jwt 字串 Google Pay API for Passes JWT。
onsuccess 字串 儲存成功回呼處理常式函式的字串名稱。
onfailure 字串 儲存失敗回呼處理常式函式的字串名稱。包含 errorCode 和 errorMessage 的錯誤物件會傳遞給這個函式。
size 字串 按鈕的顯示寬度。您可以將 size 設為 matchparent,讓寬度與父項元素的寬度一致,也可以不定義 size,讓系統依 text 設定的寬度進行調整。如要採用不同 size 設定的按鈕範例,請參閱 Google Pay API for Passes 按鈕的相關說明。
text 字串 已淘汰
textsize 字串 如果有指定 textsize=large,則在有特殊 UI 要求的情況下,文字大小和按鈕大小會大幅增加。
theme 字串 按鈕的顯示主題。可用的值為:darklight。預設的主題為 dark。如要採用不同 theme 設定的按鈕範例,請參閱 Google Pay API for Passes 按鈕的相關說明。

Google Pay API for Passes JWT

Google Pay API for Passes JWT 是用來定義要儲存的物件和類別。

通訊協定

{
  "iss": "example_service_account@developer.gserviceaccount.com",
  "aud": "google",
  "typ": "savetoandroidpay",
  "iat": 1368029586,
  "payload": {
    "eventTicketClasses": [{
      ... //Event ticket Class JSON
    }],
    "eventTicketObjects": [{
      ... //Event ticket Object JSON
    }],
    "flightClasses": [{
      ... //Flight Class JSON
    }],
    "flightObjects": [{
      ... //Flight Object JSON
    }],
    "giftCardClasses": [{
      ... //Gift card Class JSON
    }],
    "giftCardObjects": [{
      ... //Gift card Object JSON
    }],
    "loyaltyClasses": [{
      ... //Loyalty Class JSON
    }],
    "loyaltyObjects": [{
      ... //Loyalty Object JSON
    }],
    "offerClasses": [{
      ... //Offer Class JSON
    }],
    "offerObjects": [{
      ... //Offer Object JSON
    }],
    "transitClasses": [{
      ... //Transit Class JSON
    }],
    "transitObjects": [{
      ... //Transit Object JSON
    }]
  },
  "origins": ["http://baconrista.com", "https://baconrista.com"]
}

Java

WobCredentials credentials = null;
WobUtils utils = null;

// Instantiate the WobUtils class which contains handy functions
// Wob utils can be found in the quickstart sample
try {
  credentials = new WobCredentials(
    ServiceAccountEmailAddress,
    ServiceAccountPrivateKeyPath,
    ApplicationName,
    IssuerId);
  utils = new WobUtils(credentials);
} catch (GeneralSecurityException e) {
  e.printStackTrace();
} catch (IOException e) {
  e.printStackTrace();
}

// Add valid domains for the Save to Wallet button
List<String> origins = new ArrayList<String>();
origins.add("http://baconrista.com");
origins.add("https://baconrista.com");
origins.add(req.getScheme() + "://" + req.getServerName() + ":" + req.getLocalPort());

//Generate Objects and Classes here
//........

WobPayload payload = new WobPayload();
payload.addObject({WalletObject/WalletClass});

// Convert the object into a Save to Android Pay Jwt
String jwt = null;
try {
  jwt = utils.generateSaveJwt(payload, origins);
} catch (SignatureException e) {
  e.printStackTrace();
}

PHP

$requestBody = [
  "iss"=> SERVICE_ACCOUNT_EMAIL_ADDRESS,
  "aud" => "google",
  "typ" => "savetoandroidpay",
  "iat"=> time(),
  "payload" => {
    "eventTicketClasses" => [ ], # Event ticket classes
    "eventTicketObjects" => [ ], # Event ticket objects
    "flightClasses" => [ ],      # Flight classes
    "flightObjects" => [ ],      # Flight objects
    "giftCardClasses" => [ ],    # Gift card classes
    "giftCardObjects" => [ ],    # Gift card objects
    "loyaltyClasses" => [ ],     # Loyalty classes
    "loyaltyObjects" => [ ],     # Loyalty objects
    "offerClasses" => [ ],       # Offer classes
    "offerObjects" => [ ],       # Offer objects
    "transitClasses" => [ ],     # Transit classes
    "transitObjects" => [ ]      # Transit objects
  },
  "origins" => ["http://baconrista.com", "https://baconrista.com"]
]
// Generate the Save to Android Pay Jwt
echo $jwt = $assertObj->makeSignedJwt($requestBody, $client);

Python

jwt = {
  'iss': config.SERVICE_ACCOUNT_EMAIL_ADDRESS,
  'aud': 'google',
  'typ': 'savetoandroidpay',
  'iat':  int(time.time()),
  'payload': {
    'webserviceResponse': {
      'result': 'approved',
      'message': 'Success.'
    },
    'eventTicketClasses': [], # Event ticket classes
    'eventTicketObjects': [], # Event ticket objects
    'flightClasses': [],      # Flight classes
    'flightObjects': [],      # Flight objects
    'giftCardClasses': [],    # Gift card classes
    'giftCardObjects': [],    # Gift card objects
    'loyaltyClasses': [],     # Loyalty classes
    'loyaltyObjects': [],     # Loyalty objects
    'offerClasses': [],       # Offer classes
    'offerObjects': [],       # Offer objects
    'transitClasses': [],     # Transit classes
    'transitObjects': []      # Transit objects
  },
  'origins' : ['http://baconrista.com', 'https://baconrista.com']
}

// Generate the Save to Android Pay Jwt
signer = crypt.Signer.from_string(app_key)
signed_jwt = crypt.make_signed_jwt(signer, jwt)
response = webapp2.Response(signed_jwt)

注意:這些 JWT 是使用 RSA-SHA256 簽署的。簽署金鑰為 OAuth 服務帳戶產生的金鑰。

欄位 類型 必填 說明
iss 字串 您的 OAuth 2.0 服務帳戶產生的電子郵件地址。
aud 字串 目標對象。Google Pay API for Passes 物件的目標對象一律是 google
typ 字串 JWT 的類型。Google Pay API for Passes 物件的目標對象一律是 savetoandroidpay
iat 整數 核發時間,以秒為單位,自 Epoch 起算。
payload 物件 酬載物件。如需建立酬載的範例,請參閱產生 JWT 指南。酬載陣列只應包含一個物件或類別。
payload.eventTicketClasses 陣列 要儲存的活動票券類別
payload.eventTicketObjects 陣列 要儲存的活動票券物件
payload.flightClasses 陣列 要儲存的航班艙等
payload.flightObjects 陣列 要儲存的航班機票物件
payload.giftCardClasses 陣列 要儲存的儲值卡類別
payload.giftCardObjects 陣列 要儲存的儲值卡物件
payload.loyaltyClasses 陣列 要儲存的會員卡類別
payload.loyaltyObjects 陣列 要儲存的會員卡物件
payload.offerObjects 陣列 要儲存的優惠物件
payload.offerClasses 陣列 要儲存的優惠類別
payload.transitObjects 陣列 要儲存的大眾運輸票證物件
payload.transitClasses 陣列 要儲存的大眾運輸票證類別
origins 陣列 要將 JWT 儲存功能加入許可清單的網域陣列。如未定義 origins 欄位,就不會顯示 Google Pay API for Passes 按鈕。在未定義來源欄位的情況下,您可能會在瀏覽器主控台中收到「負載遭 X-Frame-Options 拒絕」或「系統拒絕顯示」訊息。

經過編碼的 JWT 應該會類似以下範例:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJnb29nbGUiLCJvcmlnaW5zIjpbImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MCIsImh0dHA6Ly93d3cuZ29vZ2xlLmNvbSJdLCJpc3MiOiJzMmFwLXRvb2wuZ29vZ2xlLmNvbUBhcHBzcG90LmdzZXJ2aWNlYWNjb3VudC5jb20iLCJpYXQiOjE1NTE5ODcxNTEsInR5cCI6InNhdmV0b3dhbGxldCIsInBheWxvYWQiOnsib2ZmZXJPYmplY3RzIjpbeyJpZCI6IjMyMDI0MTMyNDE4NDM2OTk0MDEuMDFfT2ZmZXJPYmplY3RJZCJ9XX19.maHX40WWT29TC_kEb90EKQBH9AiTYAZR3153K8UI7fznVnfjVdlwsH_GKTECV3PGXdNnKCcmatUbKsONC0bxrnAHYG02kuvA1D3hSctz_amU66ntsvGIDe13mpxTzhI8fPvt9KMP1iaO7uOJuLQIHwipu4uRFAjyFaHGVaSFaP9c53qQyb_Zgyyk50M-MhH2n4kDpstNCqUJKWaadQkOWjrtMjwGzQ_ME04lbR4wb_mfK1A7Rc1UieWkxM9aMl5TOPubBKxKRRk_CqillN8XoTl9MI5RRGPuElVO28zGpYlFS6BarzDaaUfmbRZGvfF8ZiKrHZKxVrJjfZIJ2TCcDw

用於驗證 JWT 的預覽工具

Google Pay API for Passes Merchant Center 提供的預覽工具可用於驗證 JWT 內容,或是任何個別類別或物件。如想使用這項工具,請前往發卡機構帳戶「預覽工具」的左下方

gapi.savetoandroidpay.render 函式

這個函式可讓您明確呈現 Google Pay API for Passes 按鈕。

gapi.savetoandroidpay.render("dom-container",{
  "jwt": "JWT",
  "onsuccess": "successHandler",
  "onfailure": "failureHandler"
});
欄位 類型 必填 說明
dom-container 字串 用來放置 Google Pay API for Passes 按鈕的容器 ID。
jwt 字串 定義待儲存內容的 JWT。
onsuccess 字串 儲存成功回呼處理常式函式的字串名稱。
onfailure 字串 儲存失敗回呼處理常式函式的字串名稱。包含 errorCode 和 errorMessage 的錯誤物件會傳遞給這個函式。

Google Pay API for Passes 錯誤代碼和訊息

下表列出您無法成功使用 JavaScript 按鈕儲存物件時,系統透過錯誤物件傳送給失敗回呼函式的錯誤代碼和預設錯誤訊息。

        {
          "errorCode": "errorCode",
          "errorMessage": "errorMessage"
        }
errorCode errorMessage
SERVICE_FAILURE Google Pay 伺服器發生錯誤。
CLASS_NOT_FOUND 找不到物件中參照的類別。
CLASS_MISMATCH 物件必須確實存在、屬於相同類型,且必須參照所包含的類別。
ORIGIN_MISMATCH 按鈕來源與來源清單中指定的項目不相符。
INVALID_NUM_TYPES 只能指定一個物件類型。
INVALID_SIGNATURE 無法驗證簽名。
INVALID_DUPLICATE_IDS 不允許重複的物件或類別。
INVALID_JWT JWT 無效。
INVALID_EXP_IAT JWT 已過期或尚未核發。
INVALID_AUD AUD 欄位的值無效。
INVALID_TYP TYP 欄位的值無效。
INVALID_NUM_OBJECTS 您只能為會員卡、儲值卡和優惠指定一個物件和最多一個類別。
MALFORMED_ORIGIN_URL 來源網址格式錯誤。網址必須包含通訊協定和網域。
MISSING_ORIGIN 必須指定出發地。
MISSING_FIELDS 所包含的物件或類別缺少必填欄位。

本地化

JavaScript 按鈕中的語言會根據下列條件而改變:

  1. 如果使用者已登入 Google,按鈕會依使用者的 Google 帳戶設定檔所指定的偏好語言顯示。 使用者可參閱變更語言,瞭解如何變更他們 Google 帳戶的偏好語言。
  2. 如果使用者未登入 Google,按鈕則會使用 HTTP 標題中的 ACCEPT-LANGUAGE 值。

如果您發現按鈕未根據上述邏輯以正確的語言顯示或語句不通順,請與支援小組聯絡