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` (高 30 px) 和 `standard` (高 38 px)。`height` 預設為 `small`。如要查看採用不同 `height` 設定的按鈕範例，請參閱 Google Pay API for Passes 按鈕的相關說明。
`jwt`	字串	是	Google Pay API for Passes JWT。
`onsuccess`	字串	否	儲存成功回呼處理常式函式的字串名稱。
`onfailure`	字串	否	儲存失敗回呼處理常式函式的字串名稱。包含 errorCode 和 errorMessage 的錯誤物件會傳遞給這個函式。
`onprovidejwt`	字串	否	提供 JWT 處理常式函式的字串名稱。系統將物件儲存至 Google Pay 前，可以使用這個函式來攔截或 (若可行) 操縱 JWT 資料。這個函式不使用任何參數，且必須傳回字串形式的 JWT。執行事件處理常式時，可在 `this.getOpenParams().renderData.userParams.jwt` 欄位下方擷取原始 JWT 資料。
`size`	字串	否	按鈕的顯示寬度。您可以將 `size` 設為 `matchparent`，讓寬度與父項元素的寬度相同，也可以不定義 `size`，讓系統將寬度調整為符合 `text` 設定的寬度。如要查看採用不同 `size` 設定的按鈕範例，請參閱 Google Pay API for Passes 按鈕的相關說明。
`text`	字串	否	已淘汰
`textsize`	字串	否	如有指定 `textsize=large`，系統會在有特殊 UI 要求的情況下，顯示變大許多的文字和按鈕。
`theme`	字串	否	按鈕的顯示主題。可用的值為 `dark` 和 `light`。預設的主題為 `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 按鈕。在未定義來源欄位的情況下，您可能會在瀏覽器主控台中收到「Load denied by X-Frame-Options」或「Refused to display」訊息。

經過編碼的 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 的錯誤物件會傳遞給這個函式。
`onprovidejwt`	字串	否	提供 JWT 處理常式函式的字串名稱。系統將物件儲存至 Google Pay 前，可以使用這個函式來攔截或 (若可行) 操縱 JWT 資料。這個函式不使用任何參數，且必須傳回字串形式的 JWT。執行事件處理常式時，可在 `this.getOpenParams().renderData.userParams.jwt` 欄位下方擷取原始 JWT 資料。

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 按鈕中的語言會根據下列條件而改變：

如果使用者已登入 Google，按鈕會依使用者在 Google 帳戶設定檔指定的偏好語言顯示。使用者可參閱變更語言一文，瞭解如何變更 Google 帳戶的偏好語言。
如果使用者未登入 Google 帳戶，按鈕則會使用 HTTP 標頭中的 ACCEPT-LANGUAGE 值。

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