Client reference

This reference describes the JavaScript client methods to use to implement the Google Pay API in your web applications.

Constructor

Initializes the PaymentsClient object. You must call this constructor before calling member methods.

new PaymentsClient(paymentOptions)

Arguments

Property	Description
paymentOptions	An object containing key-value pairs of Google Pay API configuration data. See PaymentOptions for the different properties configurable. Example: {environment:'PRODUCTION'}

Returns

Type	Description
google.payments.api.PaymentsClient	The PaymentsClient object.

Throws

Type	Description
Error	The passed environment property value isn't supported.

Object methods

createButton(options)

The convenience method is used to generate a Google Pay payment button styled with the latest Google Pay branding for insertion into a webpage.

The generated HTMLElement includes dynamically inserted CSS and an SVG image hosted on Google's CDN.

Reference our Brand guidelines for more information about how to select the appropriate button color and button type for your site's design. You might need to alter the dimensions of the button to match similar buttons or checkout elements on your page. Use our Customize your button tool to configure a button for your use case.

Note: Stripping onLoad and onClick event listeners when implementing the createButton API may cause the Google Pay payment button to not work as intended.

Arguments

Name	Description
options	An object that contains key-value pairs for a button configuration. See ButtonOptions for configurable properties. Example: {onClick:onGooglePaymentButtonClicked}

Returns

Type	Description
HTMLElement	An HTML <button> inside a generic flow content container such as a <div>.

Throws

Type	Description
Error	A required property isn't set.

isReadyToPay(isReadyToPayRequest)

Use the isReadyToPay(isReadyToPayRequest) method to determine a user's ability to return a form of payment from the Google Pay API.

If the browser supports Google Pay, isReadyToPay returns true. To determine whether the user is logged in to a Google account, or has already saved a payment method in Google Pay, set IsReadyToPayRequest.existingPaymentMethodRequired to true and verify that paymentMethodPresent returns true in the resolved promise. For more details, see IsReadyToPayResponse.

If PaymentsClient initialized with an environment property of TEST, paymentMethodPresent always returns true.

Arguments

Name	Description
isReadyToPayRequest	An object that contains methods of payment supported by the merchant. For details on the different properties that are configurable, see IsReadyToPayRequest.

Returns

Type	Description
Promise	Resolved: An object that contains information about the user's ability to pay. For more information, see IsReadyToPayResponse. Rejected: An error object that contains more information about the reason for rejection. For more information, see PaymentsError.

Errors

statusCode	Description
DEVELOPER_ERROR	The passed IsReadyToPayRequest object was improperly formatted, missed the minimum required parameters to determine a user's readiness to pay, or it contains an invalid parameter and/or value. The request was initiated from a security context that the payment agent or the browser chose not to fulfill. Most commonly, this is an insecure browser context error.

loadPaymentData(paymentDataRequest)

This method presents a Google Pay payment sheet that allows selection of a payment method and optionally configured parameters.

This method must be called while the browser processes an activation behavior as a result of a click event. A popup window may be presented to the user to select a payment method or other required data specified in the passed request parameter.

Arguments

Name	Description
paymentDataRequest	An object that contains key-value pairs of full Google Pay API configuration. See PaymentDataRequest for configurable properties.

Returns

Type	Description
Promise	Resolved: An object that contains the requested shopper data. See PaymentData for more information. Rejected: An object containing an error code and more information about the reason for rejection. See PaymentsError for more information.

Errors

statusCode	Description
CANCELED	The current browser or logged-in Google user isn't supported. The shopper dismissed the Google Pay payment sheet without payment authorization. The request was initiated from a security context the payment agent or the browser chose not to fulfill. Most commonly an insecure browser context. The method was called while the Google Pay payment sheet was already shown. The passed PaymentDataRequest object was rejected by the Google Pay payment sheet. Missed or incomplete PaymentMethodTokenizationSpecification parameters for your gateway or invalid parameter values are a common cause.
DEVELOPER_ERROR	The passed PaymentDataRequest object was improperly formatted, missing the minimum required parameters, or contains an invalid parameter and/or value.

prefetchPaymentData(paymentDataRequest)

Use this method to prefetch a PaymentDataRequest configuration to improve loadPaymentData execution time on later user interaction. No value is returned.

Prefetch optimizations are available on Chrome for Android.

Arguments

Name	Description
paymentDataRequest	An object that contains key-value pairs of full Google Pay API configuration. See PaymentDataRequest for configurable properties. A change in the transactionInfo property doesn't affect the cached prefetch value.

onPaymentAuthorized(paymentData)

This method is called when a payment is authorized in the payment sheet.

Note: You must resolve the promise returned by onPaymentAuthorized callback within 30 seconds. If the promise isn't resolved within this timeframe, the request times out, and the Google Pay sheet displays a CALLBACK_TIMED_OUT error to the user.

Arguments

Name	Description
paymentData	An object that contains the requested shopper data. For details, see PaymentData.

Returns

Type	Description
Promise	Resolved: An object that contains information about payment transaction results. For details, see PaymentAuthorizationResult. Rejected: An error object with an error intent and message to be rendered in the payment sheet. For details, see PaymentDataError.

onPaymentDataChanged(intermediatePaymentData)

This method handles payment data changes in the payment sheet such as shipping address and shipping options.

Note: The onPaymentAuthorized callback must also be set to use the onPaymentDataChanged callback.

Arguments

Name	Description
intermediatePaymentData	An object that contains the selected address and shipping option in the payment sheet. For details, see IntermediatePaymentData.

Returns

Type

Description

Promise

Resolved: An object that contains information about new transaction information, shipping options, and payment data errors. For details, see PaymentDataRequestUpdate. Rejected: An error object with an error intent and message to be rendered in the payment sheet. For details, see PaymentDataError. Note: Reject isn't used to update the payment sheet with new shipping options and transaction info. Don't intentionally return reject if possible.