Client reference

  • This reference provides JavaScript client methods for implementing the Google Pay API in web applications.

  • The PaymentsClient object is initialized using a constructor with payment options, enabling access to various methods.

  • Key methods include: createButton for generating a Google Pay button, isReadyToPay for checking user payment capabilities, loadPaymentData for presenting the payment sheet, and methods for handling payment authorization and data changes.

  • isReadyToPay helps determine if a user can pay with Google Pay, while loadPaymentData initiates the payment process, allowing users to select payment methods.

  • Developers can use methods like onPaymentAuthorized and onPaymentDataChanged to manage payment events and update the payment flow as needed.

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.

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.

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.

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.