用戶端參考資源

本參考資料說明可將 Google Pay API 導入網頁應用程式的 JavaScript 用戶端方法。

建構函式

初始化 PaymentsClient 物件。您必須先呼叫此建構函式，然後再呼叫成員方法。

新 PaymentsClient(paymentOptions)

引數

屬性	說明
paymentOptions	包含 Google Pay API 設定資料鍵/值組合的物件。如要瞭解其他可設定屬性的資訊，請參閱 PaymentOptions。 範例：{environment:'PRODUCTION'}

傳回

類型	說明
google.payments.api.PaymentsClient	PaymentsClient 物件。

擲回

類型	說明
Error	傳送的環境屬性值不受支援。

物件方法

createButton(options)

這個便利方法可產生使用最新 Google Pay 品牌宣傳樣式的 Google Pay 付款按鈕，方便您插入網頁。

產生的 HTMLElement 包含動態插入的 CSS 以及託管於 Google CDN 的 SVG 圖片。

請參考我們的品牌宣傳指南，進一步瞭解如何針對您網站的設計，選取適當的按鈕顏色與按鈕類型。您可能需要修改按鈕尺寸，以符合頁面中的類似按鈕或結帳元素。請使用自訂按鈕工具，依據個人用途設定按鈕。

注意：實作 createButton API 時，如果移除 onLoad 和 onClick 事件監聽器，Google Pay 付款按鈕可能無法正常運作。

引數

名稱	說明
options	包含按鈕設定鍵/值組合的物件。 如要瞭解可設定屬性的資訊，請參閱 ButtonOptions。 範例：{onClick:onGooglePaymentButtonClicked}

傳回

類型	說明
HTMLElement	一般流程內容容器 (例如 <div>) 中的 HTML <button>。

擲回

類型	說明
Error	未設定必要的屬性。

isReadyToPay(isReadyToPayRequest)

使用 isReadyToPay(isReadyToPayRequest) 方法來判斷使用者是否能從 Google Pay API 傳回付款方式。

如果瀏覽器支援 Google Pay，isReadyToPay 則會傳回 true。如要判斷使用者是否已登入 Google 帳戶，或已將付款方式儲存在 Google Pay 中，請將 IsReadyToPayRequest.existingPaymentMethodRequired 設為 true，並確認 paymentMethodPresent 會在已解析的 promise 中傳回 true。詳情請參閱 IsReadyToPayResponse。

如果 PaymentsClient 使用 TEST 環境屬性進行初始化，paymentMethodPresent 一律會傳回 true。

警告：判斷是否顯示 Google Pay 按鈕時，不應依據 existingPaymentMethodRequired。existingPaymentMethodRequired 屬性依賴 Cookie 和跨網站追蹤。如果沒有這些資訊，即使 isReadyToPayRequest.existingPaymentMethodRequired 設為 true，系統也不會傳回 paymentMethodPresent 屬性。

引數

名稱	說明
isReadyToPayRequest	包含商家支援之付款方式的物件。如要進一步瞭解各種可設定的屬性，請參閱 IsReadyToPayRequest 的說明。

傳回

類型	說明
Promise	已解析：包含使用者可否付款相關資訊的物件。詳情請參閱 IsReadyToPayResponse。 遭拒絕：包含拒絕原因詳細資訊的錯誤物件。詳情請參閱 PaymentsError。

錯誤

statusCode	說明
DEVELOPER_ERROR	傳送的 IsReadyToPayRequest 物件格式錯誤、不符合判斷使用者是否準備好付款的最少所需參數，或包含無效參數和/或值。 要求是從付款代理程式或瀏覽器選擇不完成的安全內容發出。最常見原因是瀏覽器環境不安全錯誤。

loadPaymentData(paymentDataRequest)

這個方法會顯示 Google Pay 付款畫面，允許選取付款方式及選擇設定的參數。

瀏覽器處理因點擊事件而產生的啟用行為時，須呼叫此方法。系統可能會顯示彈出式視窗，讓使用者選取付款方式或傳送要求參數中指定的其他必要資料。

引數

名稱	說明
paymentDataRequest	包含所有 Google Pay API 設定鍵/值組合的物件。 如要瞭解可設定屬性的資訊，請參閱 PaymentDataRequest。

傳回

類型	說明
Promise	已解決：包含要求的購物者資料的物件。詳情請參閱 PaymentData。 已拒絕：包含錯誤代碼與有關拒絕原因詳細資訊的物件。詳情請參閱 PaymentsError。

錯誤

statusCode	說明
CANCELED	系統不支援目前的瀏覽器或已登入的 Google 使用者。 購物者在無付款授權的情況下關閉 Google Pay 付款畫面。 付款代理程式或瀏覽器選擇不完成安全性內容，因此發出這項要求。常見原因是瀏覽器內容不安全。 在顯示 Google Pay 付款畫面時，呼叫這個方法。 傳送的 PaymentDataRequest 物件遭到 Google Pay 付款畫面拒絕。支付平台的 PaymentMethodTokenizationSpecification 參數遺失或不完整，或是參數值無效，都是常見原因。
DEVELOPER_ERROR	傳送的 PaymentDataRequest 物件格式錯誤、缺少最低必要參數，或包含無效參數和/或值。

prefetchPaymentData(paymentDataRequest)

使用這個方法可預先擷取 PaymentDataRequest 設定，以改善稍後使用者互動時的 loadPaymentData 執行時間。未傳回值。

Android 版 Chrome 可以使用預先擷取最佳化功能。

引數

名稱	說明
paymentDataRequest	包含所有 Google Pay API 設定鍵/值組合的物件。 如要瞭解可設定屬性的資訊，請參閱 PaymentDataRequest。transactionInfo 屬性中的變更不會影響已快取的預先擷取值。

onPaymentAuthorized(paymentData)

在付款畫面中授權付款時，系統會呼叫此方法。

注意：您必須在 30 秒內解決 onPaymentAuthorized 回呼傳回的 Promise。如果 promise 未在時限內解析，要求就會逾時，Google Pay 結帳畫面會向使用者顯示 CALLBACK_TIMED_OUT 錯誤。

引數

名稱	說明
paymentData	包含必要購物者資料的物件。詳情請參閱：PaymentData。

傳回

類型	說明
Promise	已解決：包含付款交易結果相關資訊的物件。 詳情請參閱：PaymentAuthorizationResult。 已拒絕：要在付款畫面中顯示的錯誤物件，內含錯誤意圖和訊息。詳情請參閱：PaymentDataError。

onPaymentDataChanged(intermediatePaymentData)

這個方法會處理付款畫面中的付款資料變更，例如運送地址和運送選項變更。

注意：您也必須設定 onPaymentAuthorized 回呼，才能使用 onPaymentDataChanged 回呼。

引數

名稱	說明
intermediatePaymentData	付款畫面中的物件，內含所選地址和運送選項。詳情請參閱：IntermediatePaymentData。

傳回

類型	說明
Promise	已解決：包含新的交易資訊、運送選項和付款資料錯誤訊息等相關資訊的物件。詳情請參閱：PaymentDataRequestUpdate。 已拒絕：要在付款畫面中顯示的錯誤物件，內含錯誤意圖和訊息。詳情請參閱：PaymentDataError。 注意事項：更新付款畫面的新運送選項和交易資訊不會遭到拒絕。請勿蓄意傳回拒絕。