@paydock/client-sdk 1.144.1-beta → 1.147.0

package/README.md

@@ -194,8 +194,48 @@ widget.setRefId('id'); // your unique identifier to identify the data
 widget.setFormFields(['phone', 'email']); // add additional fields for form of widget
 
 widget.setSupportedCardIcons(['mastercard', 'visa']); // add icons of supported card types
+
+widget.setAllowedCardSchemes(['mastercard', 'visa']); // restrict which card schemes the card number field accepts
+```
+
+### Restricting accepted card schemes
+
+`setAllowedCardSchemes(schemes)` restricts which card schemes the card number field accepts, **without** changing
+which card icons the widget displays. Call it before `load()`.
+
+```javascript
+widget.setAllowedCardSchemes(['visa', 'mastercard']);
 ```
 
+Accepted identifiers — the schemes the widget can resolve from a card number:
+
+`amex`, `ausbc`, `diners`, `discover`, `eftpos`, `japcb`, `mastercard`, `solo`, `unionpay`, `visa`
+
+Behaviour:
+
+- **Not called, or an empty array** — every scheme is accepted. Existing integrations are unaffected.
+- **Case-insensitive**, and surrounding whitespace is ignored: `' Visa '` and `'MASTERCARD'` both work. Note that
+  `setSupportedCardIcons` matches case-**sensitively**; the two methods differ here.
+- **Unsupported identifiers are ignored with a `console.warn`** naming the value, and never throw. A list in which
+  every identifier is unsupported therefore applies **no restriction at all** — check the console if a restriction
+  seems to have no effect. The icon-only values `visa_white` and `eftpos_white` are not schemes and are rejected,
+  as are `laser` and `maestro`, which the widget can never resolve from a card number.
+- **Takes precedence over `setSupportedCardIcons`.** When a non-empty list is supplied here, it is the only list
+  used for validation, and the second argument of `setSupportedCardIcons` no longer affects validation. Icons keep
+  coming from `setSupportedCardIcons`, so a scheme can legitimately be shown as an icon and still be rejected —
+  make sure that is what you intend:
+
+  ```javascript
+  widget.setSupportedCardIcons(['visa', 'mastercard', 'amex'], true);
+  widget.setAllowedCardSchemes(['visa', 'mastercard']);
+  // three icons are displayed; an Amex card is rejected
+  ```
+
+- **Calling it again replaces the previous list** rather than merging with it.
+- A card of a rejected scheme shows `Card type not accepted.` on the card number field, the submit button is
+  disabled, and the submit handler refuses the card even if the button is re-enabled outside the widget. The same
+  message is shown for a card whose scheme cannot be resolved at all.
+
 This example shows how you can use a lot of other methods to settings your form
 
 ### Error handling
@@ -355,6 +395,7 @@ When handling errors, consider:
  var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
 
  widget.setSupportedCardIcons(['mastercard', 'visa']);
+ widget.setAllowedCardSchemes(['mastercard', 'visa']);
  widget.setFormFields(['phone', 'email']);
  widget.setRefId('custom-ref-id');
     widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
@@ -400,6 +441,12 @@ When handling errors, consider:
 <dt><a href="#user-content-w_GENERIC_VALIDATORS">GENERIC_VALIDATORS</a> : <code>Record.&lt;string, string&gt;</code></dt>
 <dd><p>List of available generic form field validators and their definition</p>
 </dd>
+<dt><a href="#user-content-w_CARD_SCHEME">CARD_SCHEME</a></dt>
+<dd><p>Card schemes the widget is able to resolve from a card number, and therefore the only values
+<code>setAllowedCardSchemes</code> accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants <code>visa_white</code> / <code>eftpos_white</code>, and the <code>laser</code> / <code>maestro</code>
+identifiers the widget can never resolve — allowing those would be configuration that can never match.</p>
+</dd>
 <dt><a href="#user-content-w_TRIGGER">TRIGGER</a> : <code>object</code></dt>
 <dd><p>List of available triggers</p>
 </dd>
@@ -786,6 +833,15 @@ List of available generic form field validators and their definition
 | --- | --- | --- | --- |
 | REQUIRED | <code>string</code> | <code>&quot;required&quot;</code> | Asserts the input or form field has a value defined truthy value |
 
+<a name="w_CARD_SCHEME" id="w_CARD_SCHEME" href="#user-content-w_CARD_SCHEME">&nbsp;</a>
+
+## CARD\_SCHEME
+Card schemes the widget is able to resolve from a card number, and therefore the only values
+`setAllowedCardSchemes` accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants `visa_white` / `eftpos_white`, and the `laser` / `maestro`
+identifiers the widget can never resolve — allowing those would be configuration that can never match.
+
+**Kind**: global constant  
 <a name="w_TRIGGER" id="w_TRIGGER" href="#user-content-w_TRIGGER">&nbsp;</a>
 
 ## TRIGGER : <code>object</code>
@@ -958,6 +1014,12 @@ This example shows how you can use a lot of other methods to settings your form
 <dt><a href="#user-content-psw_PAYMENT_SOURCE_TYPE">PAYMENT_SOURCE_TYPE</a> : <code>object</code></dt>
 <dd><p>List of available payment source types</p>
 </dd>
+<dt><a href="#user-content-psw_CARD_SCHEME">CARD_SCHEME</a></dt>
+<dd><p>Card schemes the widget is able to resolve from a card number, and therefore the only values
+<code>setAllowedCardSchemes</code> accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants <code>visa_white</code> / <code>eftpos_white</code>, and the <code>laser</code> / <code>maestro</code>
+identifiers the widget can never resolve — allowing those would be configuration that can never match.</p>
+</dd>
 </dl>
 
 ## Typedefs
@@ -1509,6 +1571,15 @@ List of available payment source types
 | BANK_ACCOUNT | <code>string</code> | <code>&quot;bank_account&quot;</code> | 
 | CHECKOUT | <code>string</code> | <code>&quot;checkout&quot;</code> | 
 
+<a name="psw_CARD_SCHEME" id="psw_CARD_SCHEME" href="#user-content-psw_CARD_SCHEME">&nbsp;</a>
+
+## CARD\_SCHEME
+Card schemes the widget is able to resolve from a card number, and therefore the only values
+`setAllowedCardSchemes` accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants `visa_white` / `eftpos_white`, and the `laser` / `maestro`
+identifiers the widget can never resolve — allowing those would be configuration that can never match.
+
+**Kind**: global constant  
 <a name="psw_listener--PaymentSourceWidget" id="psw_listener--PaymentSourceWidget" href="#user-content-psw_listener--PaymentSourceWidget">&nbsp;</a>
 
 ## listener--PaymentSourceWidget : <code>function</code>
@@ -1670,6 +1741,12 @@ Then write only need 1 line of code in js to initialize widget
 <dl>
 <dt><a href="#user-content-cb_CHECKOUT_BUTTON_EVENT">CHECKOUT_BUTTON_EVENT</a> : <code>object</code></dt>
 <dd></dd>
+<dt><a href="#user-content-cb_CARD_SCHEME">CARD_SCHEME</a></dt>
+<dd><p>Card schemes the widget is able to resolve from a card number, and therefore the only values
+<code>setAllowedCardSchemes</code> accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants <code>visa_white</code> / <code>eftpos_white</code>, and the <code>laser</code> / <code>maestro</code>
+identifiers the widget can never resolve — allowing those would be configuration that can never match.</p>
+</dd>
 </dl>
 
 ## Typedefs
@@ -2203,6 +2280,15 @@ button.turnOffBackdrop();
 | FINISH | <code>string</code> | <code>&quot;finish&quot;</code> | 
 | CLOSE | <code>string</code> | <code>&quot;close&quot;</code> | 
 
+<a name="cb_CARD_SCHEME" id="cb_CARD_SCHEME" href="#user-content-cb_CARD_SCHEME">&nbsp;</a>
+
+## CARD\_SCHEME
+Card schemes the widget is able to resolve from a card number, and therefore the only values
+`setAllowedCardSchemes` accepts. This is a separate vocabulary from SUPPORTED_CARD_TYPES, which drives the
+card icons: it omits the icon-only variants `visa_white` / `eftpos_white`, and the `laser` / `maestro`
+identifiers the widget can never resolve — allowing those would be configuration that can never match.
+
+**Kind**: global constant  
 <a name="cb_listener" id="cb_listener" href="#user-content-cb_listener">&nbsp;</a>
 
 ## listener : <code>function</code>
@@ -2459,7 +2545,13 @@ After you initialized the standalone 3ds charge via `v1/charges/standalone-3ds`
                 console.log(data);
             });
             canvas3ds.on("chargeAuthChallenge", function (data) {
-                console.log(data);
+                console.log(data); // keep your loader up — the challenge page is still loading
+            });
+            canvas3ds.on("chargeAuthChallengeLoaded", function (data) {
+                console.log(data.reason); // 'load' | 'timeout' — hide your loader, the challenge is visible
+            });
+            canvas3ds.on("chargeAuthChallengeCompleted", function (data) {
+                console.log(data.source); // 'poll' | 'callback' — shopper finished, cover the challenge with "Completing verification"
             });
             canvas3ds.on("chargeAuthDecoupled", function (data) {
                 console.log(data.result.description);
@@ -2482,10 +2574,26 @@ After you initialized the standalone 3ds charge via `v1/charges/standalone-3ds`
   - A `data.status` of `rejected` will be received when the authorization was rejected.
   - A `data.status` of `invalid_event` will be received for unhandled situations.
 - The `chargeAuthChallenge` event is sent before starting a challenge flow (i.e. opening an IFrame for the customer to complete a challenge with ther bank). Once the end customer performs the challenge, the Canvas3ds will be able to identify the challenge result and will either produce a `chargeAuthSuccess` or `chargeAuthReject` event.
+- The `chargeAuthChallengeLoaded` event (SDK **v1.147.0+**) is sent once per challenge, after `chargeAuthChallenge`, when the challenge IFrame has finished loading the bank's page (its first `load` event) — this is the moment the customer can actually see the challenge. `data.reason` is `load` for a real load, or `timeout` when no load was observed within 2.5 seconds: the event is emitted anyway so you never hold a loading indicator forever (a `load` arriving later is simply ignored). Hide your loader on this event either way; `data.reason` is only informational (e.g. analytics). Not sent for decoupled challenges (no challenge IFrame).
+- The `chargeAuthChallengeCompleted` event (SDK **v1.147.0+**) is sent once the customer has finished the challenge (or approved a decoupled authentication): the bank has delivered the final result to the 3DS server and the Canvas3ds is now obtaining the outcome. Whatever the bank or the 3DS server render inside the IFrame from here on is plumbing, not UX — cover the IFrame with your own "Completing verification" state and hold it until the terminal event. `data.source` tells you how the SDK learned about it: `poll` (the 3DS server's result monitor — the usual case, it flips before the IFrame has even left the bank's page) or `callback` (the callback message carrying the outcome arrived first; the terminal event follows immediately) — handle both the same way. Sent at most once per authentication, always before `chargeAuthSuccess` / `chargeAuthReject` / `error` and never after them. A wrong OTP or a further interactive step (e.g. a second OTP screen) does **not** send it — no result has been delivered yet — so no grace timer or reveal fallback is needed on your side. Also sent for decoupled challenges.
 - The `chargeAuthDecoupled` event is sent when the flow is a decoupled challenge, alongside a `data.result.description` field that you must show to the customer, indicating the method the user must use to authenticate. For example this may happen by having the cardholder authenticating directly with their banking app through biometrics. Once the end customer does this, the Canvas3ds will be able to recognize the challenge result is ready and will either produce a `chargeAuthSuccess` or `chargeAuthReject` event.
 - The `error` event is sent if an unexpected issue with the client library occurs. In such scenarios, you should consider the autentication process as interrupted:
   - When getting this event, you will get on `data.error` the full error object.
 
+### Recommended loading indicator pattern
+
+> Requires SDK **v1.147.0 or later** (`chargeAuthChallengeLoaded` / `chargeAuthChallengeCompleted`). On older versions the same effect needs a `MutationObserver` on the container plus `load` listeners on the challenge IFrame — see the Standalone 3DS UX guide in the playground for that legacy approach.
+
+The Canvas3ds renders nothing visible until a challenge is presented, and `chargeAuthChallenge` fires when the API responds — about 1–2 seconds before the bank's page actually paints inside the IFrame. Drive a single loading indicator from the events:
+
+1. Show the loader **before** you `POST /v1/charges/standalone-3ds` and keep it up through `canvas3ds.load()` (fingerprinting and processing are invisible).
+2. Keep it up on `chargeAuthChallenge` — the challenge IFrame is being injected but is still blank.
+3. Hide it on `chargeAuthChallengeLoaded` — the challenge is visible. `data.reason` tells you whether it was a real paint (`load`) or the 2.5 s safety fallback (`timeout`); either way, no further handling is needed.
+4. Cover the IFrame with a "Completing verification" indicator on `chargeAuthChallengeCompleted` — the customer finished the challenge and the SDK is obtaining the outcome — and hold it until the terminal event. No grace timer or reveal fallback is needed: a wrong OTP or a second interactive step does not fire this event.
+5. Finish on `chargeAuthSuccess` / `chargeAuthReject` / `error`.
+
+Decoupled challenges (`chargeAuthDecoupled`) never emit `chargeAuthChallengeLoaded` (there is no challenge IFrame) but do emit `chargeAuthChallengeCompleted` once the customer approved out-of-band: show a dedicated waiting state with `data.result.description` until then, and "Completing verification" until the terminal event. Frictionless flows go straight from `load()` to the terminal event.
+
 ### Events and Values
 
 | Event Value         | Type                | Description                                                    |
@@ -2493,6 +2601,8 @@ After you initialized the standalone 3ds charge via `v1/charges/standalone-3ds`
 | <code>chargeAuthSuccess</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
 | <code>chargeAuthReject</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
 | <code>chargeAuthChallenge</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
+| <code>chargeAuthChallengeLoaded</code> | <code>object</code> | Instance of [ChallengeLoadedResponse](#cb_challengeLoadedResponse) |
+| <code>chargeAuthChallengeCompleted</code> | <code>object</code> | Instance of [ChallengeCompletedResponse](#cb_challengeCompletedResponse) |
 | <code>chargeAuthDecoupled</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
 | <code>chargeAuthInfo</code> | <code>object</code> | Instance of [ChargeEventResponse](#cb_chargeEventResponse) |
 | <code>error</code> | <code>object</code> | Instance of [chargeError](#cb_chargeError) |
@@ -2510,6 +2620,24 @@ After you initialized the standalone 3ds charge via `v1/charges/standalone-3ds`
 | <code>info</code> | <code>string</code> | info field for `chargeAuthInfo` event |
 | <code>result.description</code> | <code>string</code> [Optional] | field that you must show to the customer, indicating the method the user must use to authenticate during the decoupled challenge flow. |
 
+<a name="cb_challengeLoadedResponse" id="cb_challengeLoadedResponse"></a>
+
+### ChallengeLoadedResponse
+
+| Param                           | Type                           | Description                                                                                        |
+| ------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| <code>charge_3ds_id</code> | <code>string</code> | Universal unique transaction identifier to identify the transaction |
+| <code>reason</code> | <code>string</code> | `load` — the challenge IFrame fired its first load event; `timeout` — no load within 2.5 s, emitted so a loader is never held forever (a later load is ignored) |
+
+<a name="cb_challengeCompletedResponse" id="cb_challengeCompletedResponse"></a>
+
+### ChallengeCompletedResponse
+
+| Param                           | Type                           | Description                                                                                        |
+| ------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| <code>charge_3ds_id</code> | <code>string</code> | Universal unique transaction identifier to identify the transaction |
+| <code>source</code> | <code>string</code> | `poll` — the 3DS server's result monitor reported that the bank delivered the result (the usual case); `callback` — the callback message carrying the outcome arrived first (the terminal event follows immediately). Informational only — handle both the same way |
+
 ### ChargeError
 
 <a name="cb_chargeError" id="cb_chargeError"></a>
@@ -5652,6 +5780,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 +6298,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 +6492,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 +6675,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 +6857,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 +6975,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 +7009,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 +7374,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 +7763,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 +7826,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 +8213,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*