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`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#PaymentOptions) for the different properties configurable. Example: `{environment:'PRODUCTION'}` |

#### Returns

| Type | Description |
|---|---|
| `google.payments.api.PaymentsClient` | The `PaymentsClient` object. |

#### Throws

| Type | Description |
|---|---|
| [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error "MDN JavaScript reference: 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](https://developers.google.com/pay/api/web/guides/brand-guidelines.md.txt)
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](https://developers.google.com/pay/api/web/guides/resources/customize.md.txt) 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`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#ButtonOptions) for configurable properties. Example: `{onClick:onGooglePaymentButtonClicked}` <br /> |

#### Returns

| Type | Description |
|---|---|
| [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement "MDN JavaScript reference: HTMLElement") | An HTML `<button>` inside a generic flow content container such as a `<div>`. |

#### Throws

| Type | Description |
|---|---|
| [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error "MDN JavaScript reference: 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`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#existingPaymentMethodRequired)
to `true` and verify that
`paymentMethodPresent` returns `true` in the resolved promise. For more
details, see
[`IsReadyToPayResponse`](https://developers.google.com/pay/api/web/reference/response-objects.md.txt#IsReadyToPayResponse).

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

> [!WARNING]
> **Warning:** `existingPaymentMethodRequired` should not be relied upon when determining whether or not to show the Google Pay button. The `existingPaymentMethodRequired` property relies on cookies and cross-site tracking. If these are not available, the `paymentMethodPresent` property will not be returned, even if `isReadyToPayRequest.existingPaymentMethodRequired` is set to `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`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#IsReadyToPayRequest). |

#### Returns

| Type | Description |
|---|---|
| [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "MDN JavaScript reference: Promise") | **Resolved:** An object that contains information about the user's ability to pay. For more information, see [`IsReadyToPayResponse`](https://developers.google.com/pay/api/web/reference/response-objects.md.txt#IsReadyToPayResponse). **Rejected:** An error object that contains more information about the reason for rejection. For more information, see [`PaymentsError`.](https://developers.google.com/pay/api/web/reference/error-objects.md.txt#PaymentsError) |

#### Errors

| statusCode | Description |
|---|---|
| `DEVELOPER_ERROR` | - The passed [`IsReadyToPayRequest`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#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](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts "MDN: Secure contexts") 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](https://html.spec.whatwg.org/multipage/interaction.html#activation "HTML specification: Activation")
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`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#PaymentDataRequest) for configurable properties. |

#### Returns

| Type | Description |
|---|---|
| [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "MDN JavaScript reference: Promise") | **Resolved:** An object that contains the requested shopper data. See [PaymentData](https://developers.google.com/pay/api/web/reference/response-objects.md.txt#PaymentData) for more information. **Rejected:** An object containing an error code and more information about the reason for rejection. See [PaymentsError](https://developers.google.com/pay/api/web/reference/error-objects.md.txt#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](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts "MDN: Secure contexts"). - The method was called while the Google Pay payment sheet was already shown. - The passed [`PaymentDataRequest`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#PaymentDataRequest) object was rejected by the Google Pay payment sheet. Missed or incomplete [`PaymentMethodTokenizationSpecification` parameters](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#PaymentMethodTokenizationSpecification) for your gateway or invalid parameter values are a common cause. |
| `DEVELOPER_ERROR` | The passed [`PaymentDataRequest`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#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`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#PaymentDataRequest) for configurable properties. A change in the `transactionInfo` property doesn't affect the cached prefetch value. |

## Payment data callbacks

The following callback handlers can be passed to
[`PaymentOptions.paymentDataCallbacks`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#PaymentOptions)
to support Authorize Payments and Dynamic Price Updates.

### 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`](https://developers.google.com/pay/api/web/reference/response-objects.md.txt#PaymentData). |

#### Returns

| Type | Description |
|---|---|
| [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "MDN JavaScript reference: Promise") | **Resolved:** An object that contains information about payment transaction results. For details, see [`PaymentAuthorizationResult`](https://developers.google.com/pay/api/web/reference/response-objects.md.txt#PaymentAuthorizationResult). **Rejected:** An error object with an error intent and message to be rendered in the payment sheet. For details, see [`PaymentDataError`](https://developers.google.com/pay/api/web/reference/response-objects.md.txt#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. You must resolve the promise returned by the `onPaymentDataChanged` 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 |
|---|---|
| `intermediatePaymentData` | An object that contains the selected address and shipping option in the payment sheet. For details, see [`IntermediatePaymentData`](https://developers.google.com/pay/api/web/reference/response-objects.md.txt#IntermediatePaymentData). |

#### Returns

| Type | Description |
|---|---|
| [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "MDN JavaScript reference: Promise") | **Resolved:** An object that contains information about new transaction information, shipping options, and payment data errors. For details, see [`PaymentDataRequestUpdate`](https://developers.google.com/pay/api/web/reference/request-objects.md.txt#PaymentDataRequestUpdate). **Rejected:** An error object with an error intent and message to be rendered in the payment sheet. For details, see [`PaymentDataError`](https://developers.google.com/pay/api/web/reference/response-objects.md.txt#PaymentDataError). **Note:** Reject doesn't update the contents of the payment sheet; it only displays an error message to the user. |