用戶端參考資源

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

建構函式

初始化 PaymentsClient 物件。您必須先呼叫這個建構函式，才能呼叫成員方法。

new 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	Resolved：這個物件包含使用者付款能力的相關資訊。詳情請參閱「IsReadyToPayResponse」。 Rejected：錯誤物件，內含拒絕原因的詳細資訊。詳情請參閱 PaymentsError。

錯誤

statusCode	說明
DEVELOPER_ERROR	傳遞的 IsReadyToPayRequest 物件格式不正確、缺少判斷使用者是否準備好付款所需的最低必要參數，或包含無效的參數和/或值。 要求是從付款代理或瀏覽器選擇不執行的安全性環境發起。最常見的是不安全的瀏覽器環境錯誤。

loadPaymentData(paymentDataRequest)

這個方法會顯示 Google Pay 付款畫面，可讓使用者選取付款方式和選用參數。

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

引數

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

傳回

類型	說明
Promise	Resolved：包含所要求購物者資料的物件。詳情請參閱 PaymentData。 Rejected：包含錯誤代碼和拒絕原因詳細資訊的物件。詳情請參閱 PaymentsError。

錯誤

statusCode	說明
CANCELED	不支援目前的瀏覽器或登入的 Google 使用者。 購物者在未授權付款的情況下關閉 Google Pay 付款畫面。 要求是從付款代理或瀏覽器選擇不執行的安全性環境發起。最常見的是不安全的瀏覽器環境。 系統已顯示 Google Pay 付款畫面，但仍呼叫這個方法。 Google Pay 付款畫面拒絕了傳遞的 PaymentDataRequest 物件。常見原因包括閘道缺少 PaymentMethodTokenizationSpecification 參數、參數不完整或參數值無效。
DEVELOPER_ERROR	傳遞的 PaymentDataRequest 物件格式不正確、缺少最低必要參數，或包含無效的參數和/或值。

prefetchPaymentData(paymentDataRequest)

使用這個方法預先擷取 PaymentDataRequest 設定，可縮短 後續使用者互動時的 loadPaymentData 執行時間。不會傳回任何值。

Android 版 Google Chrome 提供預先擷取最佳化功能。

引數

名稱	說明
paymentDataRequest	包含完整 Google Pay API 設定鍵/值組合的物件。如要查看可設定的屬性，請參閱 PaymentDataRequest。變更 transactionInfo 屬性不會影響快取的預先擷取值。

付款資料回呼

下列回呼處理常式可傳遞至 PaymentOptions.paymentDataCallbacks，以支援授權付款和動態定價更新。

onPaymentAuthorized(paymentData)

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

注意：您必須 解析 onPaymentAuthorized 回呼傳回的承諾 ，並在 30 秒內完成。如果 且承諾未解決 ，要求就會逾時，Google Pay 表單會向使用者顯示 CALLBACK_TIMED_OUT 錯誤。

引數

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

傳回

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

onPaymentDataChanged(intermediatePaymentData)

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

注意：您也必須設定 onPaymentAuthorized 回呼，才能使用 onPaymentDataChanged 回呼。您必須 解析 onPaymentDataChanged 回呼傳回的 Promise ，並在 30 秒內完成。如果 承諾未解決 在時間範圍內，要求會逾時，Google Pay 表單會向使用者顯示 CALLBACK_TIMED_OUT 錯誤。

引數

hello

名稱	說明
intermediatePaymentData	這個物件包含付款畫面中選取的地址和運送選項。詳情請參閱 IntermediatePaymentData。

傳回

類型	說明
Promise	Resolved：這個物件包含新的交易資訊、運送選項和付款資料錯誤。詳情請參閱 PaymentDataRequestUpdate。 Rejected：錯誤物件，包含要在付款畫面中顯示的錯誤意圖和訊息。詳情請參閱 PaymentDataError。 注意：拒絕不會更新付款表的內容，只會向使用者顯示錯誤訊息。