@paydock/client-sdk 1.144.1-beta → 1.145.0-beta

package/README.md

@@ -5652,6 +5652,106 @@ Bear in mind that you must set an environment before calling `button.load()`.
 button.setEnv('sandbox');
 ```
 
+### Checking availability before instantiation (static)
+
+`ApplePayOpenWalletButton.checkAvailability(options)` is a **static** method so you can decide
+whether to show an Apple Pay option — or which payment method to default to — **without
+instantiating the button** and waiting for the `onUnavailable` event.
+
+> **Apple Pay is no longer Safari-only.** Since iOS 16 (third-party mobile browsers) and the
+> iOS 18 / 2025 desktop rollout, Apple Pay also works in Chrome, Edge and Firefox — including
+> on Windows — via a **cross-device QR handoff**: the user scans a code and completes the
+> payment on their iPhone. Because the paying device is often *not* the browsing device, the
+> only authoritative availability signal is the async `checkAvailability()`.
+> `applePayCapabilities()` is what Apple recommends; `canMakePayments()` is just a coarse
+> local-device hint. See
+> [Apple — Checking for Apple Pay availability](https://developer.apple.com/documentation/applepayontheweb/checking-for-apple-pay-availability).
+
+#### `ApplePayOpenWalletButton.checkAvailability(options)`
+
+The single, authoritative, cross-browser-aware check. It resolves the merchant identifier,
+loads Apple's web SDK if needed, and queries `ApplePaySession.applePayCapabilities()`.
+
+You may supply the merchant context in either of two ways:
+
+```javascript
+// 1) Lightest path — no network — when you already know the Apple merchant identifier:
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    merchant_id: 'merchant.com.example',
+});
+
+// 2) Resolve the merchant identifier from the service configuration (fetched & cached):
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    public_key_or_access_token: publicKeyOrAccessToken,
+    service_id: serviceId,
+    env: 'sandbox',
+    // Optional — which device statuses count as "available".
+    // Defaults to ['credentials_available', 'credentials_status_unknown'].
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown'],
+});
+```
+
+**Result shape (`ApplePayAvailabilityResult`):**
+
+```javascript
+{
+    available: true,                  // verdict vs the allowed capability set
+    supported: true,                  // Apple Pay usable here AT ALL (incl. cross-device QR)
+    has_native_session: false,        // native same-device session present (canMakePayments)
+    payment_credential_status:        // OUTPUT — the device's reported status
+        'paymentCredentialStatusUnknown',
+    reason: undefined,                // set when not available, see below
+}
+```
+
+**Inferring the transport (Apple does not expose it directly):**
+- `available && has_native_session` ⇒ **native** Apple Pay sheet is likely (Safari on an Apple device).
+- `available && !has_native_session` ⇒ **cross-device / QR** handoff is likely (e.g. Chrome on desktop).
+
+`payment_credential_status` is the device's actual status:
+`'paymentCredentialsAvailable'`, `'paymentCredentialStatusUnknown'`,
+`'paymentCredentialsUnavailable'`, or `'applePayUnsupported'`. **Third-party / desktop
+browsers normally report `paymentCredentialStatusUnknown`** (Apple can't see the remote
+iPhone's cards until the user scans the QR), which is why the default allowed set includes it.
+
+The `apple_pay_capabilities` **input** maps to those statuses
+(`credentials_available` → `paymentCredentialsAvailable`,
+`credentials_status_unknown` → `paymentCredentialStatusUnknown`,
+`credentials_unavailable` → `paymentCredentialsUnavailable`) and decides which ones make
+`available` true. When omitted, **both** `paymentCredentialsAvailable` and
+`paymentCredentialStatusUnknown` count — narrow it to `['credentials_available']` only if you
+want to require a confirmed local card (this will hide the button in cross-browser/QR contexts).
+
+When `available` is `false`, `reason` is one of: `'unsupported_browser'`,
+`'missing_merchant_id'`, `'service_type_mismatch'`, `'config_fetch_failed'`,
+`'sdk_load_failed'`, `'query_failed'`, `'no_credentials'`, or `'no_native_session'`
+(only from the synchronous check below).
+
+```javascript
+const result = await paydock.ApplePayOpenWalletButton.checkAvailability({ merchant_id: merchantId });
+if (result.available) {
+    renderApplePayButton();
+} else {
+    console.log('Apple Pay unavailable:', result.reason, result.payment_credential_status);
+}
+```
+
+**Synchronous native-only fast check (`sync: true`).** Pass `{ sync: true }` for a cheap,
+network-free pre-check that resolves immediately — it runs only the native same-device check
+(`window.ApplePaySession` + `canMakePayments()`), with no merchant resolution, SDK load, or
+`applePayCapabilities()` query. In this mode `available` reflects the native session only and
+`payment_credential_status` is `undefined`. It is a Safari-oriented hint and is **not**
+authoritative for cross-browser / QR availability (which require the full async check above).
+
+```javascript
+const { has_native_session } = await paydock.ApplePayOpenWalletButton.checkAvailability({
+    sync: true,
+});
+if (has_native_session) {
+    // Native Apple Pay is ready on this device (Safari fast path).
+}
+```
+
 ### Full Apple Pay example
 
 ```html
@@ -6070,6 +6170,58 @@ The GooglePayOpenWalletButton constructor accepts the following parameters:
 
 > **Note:** Required meta fields (`amount`, `currency`, `country`) are validated automatically by the `GooglePayOpenWalletButton` class. You do not need to specify them manually.
 
+### Checking availability before instantiation (static)
+
+`GooglePayOpenWalletButton.checkAvailability(options)` is a **static** method that reports
+whether Google Pay can be used in the current context **without instantiating the button**.
+It loads the Google Pay JS SDK if needed and runs `PaymentsClient.isReadyToPay()`.
+
+Unlike Apple Pay, **all options are optional** — Google Pay's readiness check does not
+require a merchant identifier. Supplying `publicKeyOrAccessToken` + `serviceId` additionally
+validates that the service is a Google Pay service (and resolves the merchant id).
+
+```javascript
+// Simplest form — no merchant context needed:
+const result = await paydock.GooglePayOpenWalletButton.checkAvailability();
+
+// Or validate the service is a Google Pay service while checking:
+const result = await paydock.GooglePayOpenWalletButton.checkAvailability({
+    public_key_or_access_token: publicKeyOrAccessToken,
+    service_id: serviceId,
+    env: 'sandbox',
+});
+```
+
+**Result shape (`GooglePayAvailabilityResult`):**
+
+```javascript
+{
+    available: true,             // isReadyToPay().result — ready to pay in this context
+    supported: true,             // the Google Pay JS API is present and the query ran
+    payment_method_present: true, // OUTPUT — whether the buyer already has a usable card
+    reason: undefined,           // set when not available, see below
+}
+```
+
+> **Note:** the static check uses the **default** card configuration (standard auth methods
+> and card networks). A button instance configured with a custom `card_config` may produce a
+> different result.
+
+When `available` is `false`, `reason` is one of: `'unsupported_browser'`,
+`'service_type_mismatch'`, `'config_fetch_failed'`, `'sdk_load_failed'`, `'query_failed'`,
+`'no_payment_method'`, or `'api_not_loaded'` (only from the synchronous check below).
+
+**Synchronous fast check (`sync: true`).** Google Pay has no synchronous device/card
+capability API, so `{ sync: true }` only reports whether the Google Pay JS API is already
+present in the page — it does **not** run `isReadyToPay()`:
+
+```javascript
+const { available } = await paydock.GooglePayOpenWalletButton.checkAvailability({
+    sync: true,
+});
+// `available` here means "the Google Pay JS API script is loaded", not "ready to pay".
+```
+
 ### Full Google Pay Example
 
 ```html
@@ -6212,12 +6364,28 @@ Both `ApplePayOpenWalletButton` and `GooglePayOpenWalletButton` share the same e
 
 ### Checking for button availability
 
-If the customer's browser is not supported, or the customer does not have any card added to their wallet, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.
+There are two ways to know whether a wallet is available:
+
+**1. After `load()` — the `onUnavailable()` callback.** If the customer's browser is not supported, or the customer does not have any card added to their wallet, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.
 
 ```javascript
 button.onUnavailable(({ data }) => console.log("No wallet button available", data));
 ```
 
+**2. Before instantiation — the static `checkAvailability()` method.** Each button class exposes a static `checkAvailability(options)` that resolves availability **without instantiating the button**, so you can decide whether to render a wallet option (or which payment method to default to) up front. The options and result are wallet-specific — see [Apple Pay → Checking availability before instantiation](#checking-availability-before-instantiation-static) and [Google Pay → Checking availability before instantiation](#checking-availability-before-instantiation-static-1).
+
+```javascript
+// Apple Pay
+const apple = await paydock.ApplePayOpenWalletButton.checkAvailability({ merchant_id: merchantId });
+
+// Google Pay (merchant context optional)
+const google = await paydock.GooglePayOpenWalletButton.checkAvailability();
+
+if (apple.available || google.available) {
+    // Show a wallet payment option.
+}
+```
+
 ### Service type validation
 
 Each button validates that the service configuration matches its expected wallet type. If you use an Apple Pay service ID with `GooglePayOpenWalletButton` (or vice versa), an error will be emitted via `onError`:
@@ -6379,7 +6547,7 @@ A full description of the [ApplePayOpenWalletMeta](#ApplePayOpenWalletMeta) prop
 - `request_shipping?: boolean`: Enable shipping address collection
 - `shipping_options?: IApplePayShippingOption[]`: Array of shipping options
 - `show_billing_address?: boolean`: Show billing address fields
-- `apple_pay_capabilities?: string[]`: Device capabilities
+- `apple_pay_capabilities?: string[]`: Device credential statuses that make the button render. **Defaults to `['credentials_available', 'credentials_status_unknown']`**: `credentials_available` means the device has a confirmed Apple Pay card ready to use; `credentials_status_unknown` means a local card can't be confirmed but Apple Pay can still proceed (e.g. the cross-device QR flow used by Chrome, Edge and Firefox). Narrow to `['credentials_available']` to require a confirmed local card.
 - `merchant_capabilities?: string[]`: Merchant capabilities
 - `supported_networks?: string[]`: Supported payment networks
 - `required_billing_contact_fields?: string[]`: Required billing contact fields
@@ -6561,6 +6729,37 @@ Apple will determine if the device has an ApplePay wallet available and at least
 <dt><a href="#GooglePayOpenWalletMeta">GooglePayOpenWalletMeta</a> : <code>object</code></dt>
 <dd><p>Interface for Google Pay-specific metadata.</p>
 </dd>
+<dt><a href="#OpenWalletAvailabilityOptions">OpenWalletAvailabilityOptions</a> : <code>object</code></dt>
+<dd><p>Base options shared by every wallet&#39;s static availability check
+(e.g. <a href="#ApplePayOpenWalletButton">ApplePayOpenWalletButton</a>.checkAvailability). Wallet-specific option
+interfaces (such as <a href="#ApplePayAvailabilityOptions">ApplePayAvailabilityOptions</a>) extend this.</p>
+</dd>
+<dt><a href="#OpenWalletAvailabilityResult">OpenWalletAvailabilityResult</a> : <code>object</code></dt>
+<dd><p>Base result shared by every wallet&#39;s static availability check. Wallet-specific
+result interfaces (such as <a href="#ApplePayAvailabilityResult">ApplePayAvailabilityResult</a>) extend this.</p>
+</dd>
+<dt><a href="#ApplePayAvailabilityOptions">ApplePayAvailabilityOptions</a> : <code>object</code></dt>
+<dd><p>Options for <code>ApplePayOpenWalletButton.checkAvailability</code>. Extends
+<a href="#OpenWalletAvailabilityOptions">OpenWalletAvailabilityOptions</a>. Provide <code>merchant_id</code> directly to skip the network
+call, <strong>or</strong> provide <code>public_key_or_access_token</code> + <code>service_id</code> to resolve the merchant
+identifier from the service configuration.</p>
+</dd>
+<dt><a href="#ApplePayAvailabilityResult">ApplePayAvailabilityResult</a> : <code>object</code></dt>
+<dd><p>Result of <code>ApplePayOpenWalletButton.checkAvailability</code>. Extends
+<a href="#OpenWalletAvailabilityResult">OpenWalletAvailabilityResult</a>.</p>
+<p>Infer the transport (Apple does not expose it directly): <code>available &amp;&amp; has_native_session</code>
+⇒ native sheet likely; <code>available &amp;&amp; !has_native_session</code> ⇒ cross-device / QR handoff likely.</p>
+</dd>
+<dt><a href="#GooglePayAvailabilityOptions">GooglePayAvailabilityOptions</a> : <code>object</code></dt>
+<dd><p>Options for <code>GooglePayOpenWalletButton.checkAvailability</code>. Extends
+<a href="#OpenWalletAvailabilityOptions">OpenWalletAvailabilityOptions</a>. All fields are optional — Google Pay&#39;s
+<code>isReadyToPay</code> check does not require a merchant identifier. Supplying
+<code>public_key_or_access_token</code> + <code>service_id</code> additionally validates the service type.</p>
+</dd>
+<dt><a href="#GooglePayAvailabilityResult">GooglePayAvailabilityResult</a> : <code>object</code></dt>
+<dd><p>Result of <code>GooglePayOpenWalletButton.checkAvailability</code>. Extends
+<a href="#OpenWalletAvailabilityResult">OpenWalletAvailabilityResult</a>.</p>
+</dd>
 <dt><a href="#OnClickEventData">OnClickEventData</a> : <code>object</code></dt>
 <dd><p>Interface for OnClickEventData.
 Emitted when the wallet button is clicked.</p>
@@ -6648,7 +6847,7 @@ Apple will determine if the device has an ApplePay wallet available and at least
 | [shipping_options] | [<code>Array.&lt;IApplePayShippingOption&gt;</code>](#IApplePayShippingOption) | Array of available shipping options. The first item is used as the default selected option. Requires `request_shipping` to be `true`. |
 | [show_billing_address] | <code>boolean</code> | Show billing address fields in the Apple Pay sheet. |
 | store_name | <code>string</code> | The merchant's store name displayed during payment. |
-| [apple_pay_capabilities] | <code>Array.&lt;(&#x27;credentials\_available&#x27;\|&#x27;credentials\_status\_unknown&#x27;\|&#x27;credentials\_unavailable&#x27;)&gt;</code> | Device capabilities needed for the wallet button to be available. |
+| [apple_pay_capabilities] | <code>Array.&lt;(&#x27;credentials\_available&#x27;\|&#x27;credentials\_status\_unknown&#x27;\|&#x27;credentials\_unavailable&#x27;)&gt;</code> | Device credential statuses that make the button render. Defaults to `['credentials_available', 'credentials_status_unknown']`: `credentials_available` means the device has a confirmed Apple Pay card ready to use; `credentials_status_unknown` means a local card can't be confirmed but Apple Pay can still proceed (e.g. the cross-device QR flow used by Chrome, Edge and Firefox). Narrow to `['credentials_available']` to require a confirmed local card. |
 | [merchant_capabilities] | <code>Array.&lt;(&#x27;supports3DS&#x27;\|&#x27;supportsEMV&#x27;\|&#x27;supportsCredit&#x27;\|&#x27;supportsDebit&#x27;)&gt;</code> | Array of merchant capabilities influencing the transaction processing features available. |
 | [supported_networks] | <code>Array.&lt;(&#x27;visa&#x27;\|&#x27;masterCard&#x27;\|&#x27;amex&#x27;\|&#x27;chinaUnionPay&#x27;\|&#x27;discover&#x27;\|&#x27;interac&#x27;\|&#x27;jcb&#x27;\|&#x27;privateLabel&#x27;)&gt;</code> | List of payment networks supported for Apple Pay transactions. |
 | [required_billing_contact_fields] | <code>Array.&lt;(&#x27;email&#x27;\|&#x27;name&#x27;\|&#x27;phone&#x27;\|&#x27;postalAddress&#x27;)&gt;</code> | Contact fields required from the user for billing purposes. Phone and email are currently not returned by Apple. |
@@ -6682,6 +6881,105 @@ Interface for Google Pay-specific metadata.
 | [style.button_color] | <code>GooglePayButtonColor</code> | The color of the Google Pay button (`'default'`, `'black'`, `'white'`). |
 | [style.button_size_mode] | <code>GooglePayButtonSizeMode</code> | The size mode (`'static'`, `'fill'`). |
 
+<a name="OpenWalletAvailabilityOptions" id="OpenWalletAvailabilityOptions" href="#OpenWalletAvailabilityOptions">&nbsp;</a>
+
+## OpenWalletAvailabilityOptions : <code>object</code>
+Base options shared by every wallet's static availability check
+(e.g. [ApplePayOpenWalletButton](#ApplePayOpenWalletButton).checkAvailability). Wallet-specific option
+interfaces (such as [ApplePayAvailabilityOptions](#ApplePayAvailabilityOptions)) extend this.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [public_key_or_access_token] | <code>string</code> | Public key or access token used to fetch the service config when needed. |
+| [service_id] | <code>string</code> | Service ID — used with `public_key_or_access_token` to resolve the wallet configuration. |
+| [env] | <code>string</code> | Environment for the config fetch (e.g. `'sandbox'`). Defaults to the SDK default. |
+| [sync] | <code>boolean</code> | When `true`, performs only the cheap, network-free synchronous check and resolves immediately — no config fetch, SDK load, or remote capability query. |
+
+<a name="OpenWalletAvailabilityResult" id="OpenWalletAvailabilityResult" href="#OpenWalletAvailabilityResult">&nbsp;</a>
+
+## OpenWalletAvailabilityResult : <code>object</code>
+Base result shared by every wallet's static availability check. Wallet-specific
+result interfaces (such as [ApplePayAvailabilityResult](#ApplePayAvailabilityResult)) extend this.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| available | <code>boolean</code> | Convenience verdict: the wallet is usable for a payment in the current context. |
+| supported | <code>boolean</code> | Whether the wallet is supported here at all (may be available via a fallback flow). |
+| [reason] | <code>string</code> | Machine-readable reason when not available. |
+
+<a name="ApplePayAvailabilityOptions" id="ApplePayAvailabilityOptions" href="#ApplePayAvailabilityOptions">&nbsp;</a>
+
+## ApplePayAvailabilityOptions : <code>object</code>
+Options for `ApplePayOpenWalletButton.checkAvailability`. Extends
+[OpenWalletAvailabilityOptions](#OpenWalletAvailabilityOptions). Provide `merchant_id` directly to skip the network
+call, **or** provide `public_key_or_access_token` + `service_id` to resolve the merchant
+identifier from the service configuration.
+
+**Kind**: global interface  
+**Extends**: [<code>OpenWalletAvailabilityOptions</code>](#OpenWalletAvailabilityOptions)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [merchant_id] | <code>string</code> | Apple merchant identifier. Provide this OR (`public_key_or_access_token` + `service_id`). |
+| [apple_pay_capabilities] | <code>Array.&lt;(&#x27;credentials\_available&#x27;\|&#x27;credentials\_status\_unknown&#x27;\|&#x27;credentials\_unavailable&#x27;)&gt;</code> | Device credential statuses that count as available. Defaults to `['credentials_available', 'credentials_status_unknown']` — `credentials_status_unknown` is what third-party / cross-device (QR) browsers report, so the default keeps Apple Pay visible outside Safari. |
+| [sync] | <code>boolean</code> | When `true`, runs only the synchronous native same-device check (`window.ApplePaySession` + `canMakePayments()`) and resolves immediately — no merchant resolution, SDK load, or `applePayCapabilities()` query. In this mode `available` reflects the native session only and `payment_credential_status` is `undefined`; it is **not** authoritative for cross-browser / QR availability. |
+
+<a name="ApplePayAvailabilityResult" id="ApplePayAvailabilityResult" href="#ApplePayAvailabilityResult">&nbsp;</a>
+
+## ApplePayAvailabilityResult : <code>object</code>
+Result of `ApplePayOpenWalletButton.checkAvailability`. Extends
+[OpenWalletAvailabilityResult](#OpenWalletAvailabilityResult).
+
+Infer the transport (Apple does not expose it directly): `available && has_native_session`
+⇒ native sheet likely; `available && !has_native_session` ⇒ cross-device / QR handoff likely.
+
+**Kind**: global interface  
+**Extends**: [<code>OpenWalletAvailabilityResult</code>](#OpenWalletAvailabilityResult)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| available | <code>boolean</code> | Whether the device credential status is within the allowed capability set. |
+| supported | <code>boolean</code> | Whether Apple Pay is usable here at all (incl. the cross-device QR flow). Derived from `payment_credential_status` (anything other than `applePayUnsupported`); falls back to the native `canMakePayments()` signal when the capabilities query could not run. |
+| has_native_session | <code>boolean</code> | Whether a native, same-device Apple Pay session is present right now (`ApplePaySession` exists and `canMakePayments()` is `true`). |
+| [payment_credential_status] | <code>&#x27;paymentCredentialsAvailable&#x27;</code> \| <code>&#x27;paymentCredentialStatusUnknown&#x27;</code> \| <code>&#x27;paymentCredentialsUnavailable&#x27;</code> \| <code>&#x27;applePayUnsupported&#x27;</code> | The raw device-reported credential status. Undefined when unsupported or not queried. |
+| [reason] | <code>string</code> | Machine-readable reason when not available: `'unsupported_browser'`, `'missing_merchant_id'`, `'service_type_mismatch'`, `'config_fetch_failed'`, `'sdk_load_failed'`, `'query_failed'`, `'no_credentials'`, or `'no_native_session'` (only from the synchronous `sync: true` check). |
+
+<a name="GooglePayAvailabilityOptions" id="GooglePayAvailabilityOptions" href="#GooglePayAvailabilityOptions">&nbsp;</a>
+
+## GooglePayAvailabilityOptions : <code>object</code>
+Options for `GooglePayOpenWalletButton.checkAvailability`. Extends
+[OpenWalletAvailabilityOptions](#OpenWalletAvailabilityOptions). All fields are optional — Google Pay's
+`isReadyToPay` check does not require a merchant identifier. Supplying
+`public_key_or_access_token` + `service_id` additionally validates the service type.
+
+**Kind**: global interface  
+**Extends**: [<code>OpenWalletAvailabilityOptions</code>](#OpenWalletAvailabilityOptions)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [merchant_id] | <code>string</code> | Google Pay gateway merchant identifier. Optional; the readiness check runs without it. |
+| [sync] | <code>boolean</code> | When `true`, reports only whether the Google Pay JS API is already present in the page (no `isReadyToPay` call). It does **not** run the device/card readiness check. |
+
+<a name="GooglePayAvailabilityResult" id="GooglePayAvailabilityResult" href="#GooglePayAvailabilityResult">&nbsp;</a>
+
+## GooglePayAvailabilityResult : <code>object</code>
+Result of `GooglePayOpenWalletButton.checkAvailability`. Extends
+[OpenWalletAvailabilityResult](#OpenWalletAvailabilityResult).
+
+**Kind**: global interface  
+**Extends**: [<code>OpenWalletAvailabilityResult</code>](#OpenWalletAvailabilityResult)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| available | <code>boolean</code> | Whether Google Pay is ready to pay in the current context (from `isReadyToPay().result`). |
+| supported | <code>boolean</code> | Whether the Google Pay JS API is present and the readiness query could run. |
+| [payment_method_present] | <code>boolean</code> | Google's `isReadyToPay` `paymentMethodPresent` — whether the buyer already has a usable payment method. Undefined when not reported. |
+| [reason] | <code>string</code> | Machine-readable reason when not available: `'unsupported_browser'`, `'service_type_mismatch'`, `'config_fetch_failed'`, `'sdk_load_failed'`, `'query_failed'`, `'no_payment_method'`, or `'api_not_loaded'` (only from the synchronous `sync: true` check). |
+
 <a name="OnClickEventData" id="OnClickEventData" href="#OnClickEventData">&nbsp;</a>
 
 ## OnClickEventData : <code>object</code>
@@ -6948,20 +7246,23 @@ if the service type does not match Apple Pay.
 
 * [ApplePayOpenWalletButton](#ApplePayOpenWalletButton) ⇐ [<code>OpenWalletButtons</code>](#OpenWalletButtons)
     * [new ApplePayOpenWalletButton(selector, publicKeyOrAccessToken, serviceId, meta)](#new_ApplePayOpenWalletButton_new)
-    * [.load()](#OpenWalletButtons+load)
-    * [.enable()](#OpenWalletButtons+enable)
-    * [.disable()](#OpenWalletButtons+disable)
-    * [.setEnv(env, [alias])](#OpenWalletButtons+setEnv)
-    * [.setMeta(meta)](#OpenWalletButtons+setMeta)
-    * [.destroy()](#OpenWalletButtons+destroy)
-    * [.onClick(handler)](#OpenWalletButtons+onClick)
-    * [.onSuccess(handler)](#OpenWalletButtons+onSuccess)
-    * [.onUnavailable(handler)](#OpenWalletButtons+onUnavailable)
-    * [.onError(handler)](#OpenWalletButtons+onError)
-    * [.onCancel(handler)](#OpenWalletButtons+onCancel)
-    * [.onLoaded(handler)](#OpenWalletButtons+onLoaded)
-    * [.onShippingAddressChange(handler)](#OpenWalletButtons+onShippingAddressChange)
-    * [.onShippingOptionsChange(handler)](#OpenWalletButtons+onShippingOptionsChange)
+    * _instance_
+        * [.load()](#OpenWalletButtons+load)
+        * [.enable()](#OpenWalletButtons+enable)
+        * [.disable()](#OpenWalletButtons+disable)
+        * [.setEnv(env, [alias])](#OpenWalletButtons+setEnv)
+        * [.setMeta(meta)](#OpenWalletButtons+setMeta)
+        * [.destroy()](#OpenWalletButtons+destroy)
+        * [.onClick(handler)](#OpenWalletButtons+onClick)
+        * [.onSuccess(handler)](#OpenWalletButtons+onSuccess)
+        * [.onUnavailable(handler)](#OpenWalletButtons+onUnavailable)
+        * [.onError(handler)](#OpenWalletButtons+onError)
+        * [.onCancel(handler)](#OpenWalletButtons+onCancel)
+        * [.onLoaded(handler)](#OpenWalletButtons+onLoaded)
+        * [.onShippingAddressChange(handler)](#OpenWalletButtons+onShippingAddressChange)
+        * [.onShippingOptionsChange(handler)](#OpenWalletButtons+onShippingOptionsChange)
+    * _static_
+        * [.checkAvailability([options])](#ApplePayOpenWalletButton.checkAvailability) ⇒ [<code>Promise.&lt;ApplePayAvailabilityResult&gt;</code>](#ApplePayAvailabilityResult)
 
 <a name="new_ApplePayOpenWalletButton_new" id="new_ApplePayOpenWalletButton_new" href="#new_ApplePayOpenWalletButton_new">&nbsp;</a>
 
@@ -7334,6 +7635,54 @@ button.onShippingOptionsChange((data) => {
   };
 });
 ```
+<a name="ApplePayOpenWalletButton.checkAvailability" id="ApplePayOpenWalletButton.checkAvailability" href="#ApplePayOpenWalletButton.checkAvailability">&nbsp;</a>
+
+### ApplePayOpenWalletButton.checkAvailability([options]) ⇒ [<code>Promise.&lt;ApplePayAvailabilityResult&gt;</code>](#ApplePayAvailabilityResult)
+Checks Apple Pay availability **without instantiating the button** — the single,
+authoritative, cross-browser-aware availability entry point.
+
+Resolves the merchant identifier (either supplied directly or fetched from the
+service configuration), loads Apple's web SDK if needed, then queries
+`ApplePaySession.applePayCapabilities()`. Returns a convenience `available` verdict
+(computed against `apple_pay_capabilities`), the raw device-reported
+`payment_credential_status`, and `has_native_session` so callers can infer the transport:
+`available && has_native_session` ⇒ native sheet likely; `available && !has_native_session`
+⇒ cross-device / QR handoff likely.
+
+Pass `{ sync: true }` for a cheap, network-free native same-device pre-check that
+resolves immediately (see [ApplePayAvailabilityOptions.sync](ApplePayAvailabilityOptions.sync)).
+
+**Kind**: static method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+**Returns**: [<code>Promise.&lt;ApplePayAvailabilityResult&gt;</code>](#ApplePayAvailabilityResult) - The availability result.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [options] | [<code>ApplePayAvailabilityOptions</code>](#ApplePayAvailabilityOptions) | Merchant context, allowed capabilities, and mode. |
+
+**Example**  
+```js
+// Lightest path — no network, when you already know the merchant identifier:
+const result = await ApplePayOpenWalletButton.checkAvailability({ merchant_id });
+```
+**Example**  
+```js
+// Resolve the merchant identifier from the service configuration:
+const result = await ApplePayOpenWalletButton.checkAvailability({
+  public_key_or_access_token,
+  service_id,
+  env: 'sandbox',
+});
+if (result.available) {
+  // Render the Apple Pay button (native sheet or cross-device QR, per has_native_session).
+} else {
+  console.log('Unavailable:', result.reason, result.payment_credential_status);
+}
+```
+**Example**  
+```js
+// Synchronous native-only fast check (no network / SDK load):
+const { has_native_session } = await ApplePayOpenWalletButton.checkAvailability({ sync: true });
+```
 <a name="GooglePayOpenWalletButton" id="GooglePayOpenWalletButton" href="#GooglePayOpenWalletButton">&nbsp;</a>
 
 ## GooglePayOpenWalletButton ⇐ [<code>OpenWalletButtons</code>](#OpenWalletButtons)
@@ -7349,20 +7698,23 @@ if the service type does not match Google Pay.
 
 * [GooglePayOpenWalletButton](#GooglePayOpenWalletButton) ⇐ [<code>OpenWalletButtons</code>](#OpenWalletButtons)
     * [new GooglePayOpenWalletButton(selector, publicKeyOrAccessToken, serviceId, meta)](#new_GooglePayOpenWalletButton_new)
-    * [.load()](#OpenWalletButtons+load)
-    * [.enable()](#OpenWalletButtons+enable)
-    * [.disable()](#OpenWalletButtons+disable)
-    * [.setEnv(env, [alias])](#OpenWalletButtons+setEnv)
-    * [.setMeta(meta)](#OpenWalletButtons+setMeta)
-    * [.destroy()](#OpenWalletButtons+destroy)
-    * [.onClick(handler)](#OpenWalletButtons+onClick)
-    * [.onSuccess(handler)](#OpenWalletButtons+onSuccess)
-    * [.onUnavailable(handler)](#OpenWalletButtons+onUnavailable)
-    * [.onError(handler)](#OpenWalletButtons+onError)
-    * [.onCancel(handler)](#OpenWalletButtons+onCancel)
-    * [.onLoaded(handler)](#OpenWalletButtons+onLoaded)
-    * [.onShippingAddressChange(handler)](#OpenWalletButtons+onShippingAddressChange)
-    * [.onShippingOptionsChange(handler)](#OpenWalletButtons+onShippingOptionsChange)
+    * _instance_
+        * [.load()](#OpenWalletButtons+load)
+        * [.enable()](#OpenWalletButtons+enable)
+        * [.disable()](#OpenWalletButtons+disable)
+        * [.setEnv(env, [alias])](#OpenWalletButtons+setEnv)
+        * [.setMeta(meta)](#OpenWalletButtons+setMeta)
+        * [.destroy()](#OpenWalletButtons+destroy)
+        * [.onClick(handler)](#OpenWalletButtons+onClick)
+        * [.onSuccess(handler)](#OpenWalletButtons+onSuccess)
+        * [.onUnavailable(handler)](#OpenWalletButtons+onUnavailable)
+        * [.onError(handler)](#OpenWalletButtons+onError)
+        * [.onCancel(handler)](#OpenWalletButtons+onCancel)
+        * [.onLoaded(handler)](#OpenWalletButtons+onLoaded)
+        * [.onShippingAddressChange(handler)](#OpenWalletButtons+onShippingAddressChange)
+        * [.onShippingOptionsChange(handler)](#OpenWalletButtons+onShippingOptionsChange)
+    * _static_
+        * [.checkAvailability([options])](#GooglePayOpenWalletButton.checkAvailability) ⇒ [<code>Promise.&lt;GooglePayAvailabilityResult&gt;</code>](#GooglePayAvailabilityResult)
 
 <a name="new_GooglePayOpenWalletButton_new" id="new_GooglePayOpenWalletButton_new" href="#new_GooglePayOpenWalletButton_new">&nbsp;</a>
 
@@ -7733,6 +8085,45 @@ button.onShippingOptionsChange((data) => {
   };
 });
 ```
+<a name="GooglePayOpenWalletButton.checkAvailability" id="GooglePayOpenWalletButton.checkAvailability" href="#GooglePayOpenWalletButton.checkAvailability">&nbsp;</a>
+
+### GooglePayOpenWalletButton.checkAvailability([options]) ⇒ [<code>Promise.&lt;GooglePayAvailabilityResult&gt;</code>](#GooglePayAvailabilityResult)
+Checks Google Pay availability **without instantiating the button** — the static
+availability entry point.
+
+Loads the Google Pay JS SDK if needed, then runs `PaymentsClient.isReadyToPay()` using
+the **default** card configuration (a button instance with a custom `card_config` may
+produce a different result). All options are optional — unlike Apple Pay, Google Pay's
+readiness check does not require a merchant identifier; supplying `service_id` +
+`public_key_or_access_token` additionally validates that the service is a Google Pay service.
+
+Pass `{ sync: true }` for a cheap, network-free check that only reports whether the
+Google Pay JS API is already present (see [GooglePayAvailabilityOptions.sync](GooglePayAvailabilityOptions.sync)).
+
+**Kind**: static method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+**Returns**: [<code>Promise.&lt;GooglePayAvailabilityResult&gt;</code>](#GooglePayAvailabilityResult) - The availability result.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [options] | [<code>GooglePayAvailabilityOptions</code>](#GooglePayAvailabilityOptions) | Optional merchant context and mode. |
+
+**Example**  
+```js
+// Simplest form — no merchant context needed:
+const result = await GooglePayOpenWalletButton.checkAvailability();
+if (result.available) {
+  // Render the Google Pay button.
+}
+```
+**Example**  
+```js
+// Validate the service is a Google Pay service while checking:
+const result = await GooglePayOpenWalletButton.checkAvailability({
+  public_key_or_access_token,
+  service_id,
+  env: 'sandbox',
+});
+```
 <a name="OpenWalletButtons" id="OpenWalletButtons" href="#OpenWalletButtons">&nbsp;</a>
 
 ## *OpenWalletButtons*