@paydock/client-sdk 1.139.0 → 1.140.1

package/docs/open-wallet-buttons.md

@@ -0,0 +1,1652 @@
+## Classes
+
+<dl>
+<dt><a href="#ApplePayOpenWalletButton">ApplePayOpenWalletButton</a> ⇐ <code><a href="#OpenWalletButtons">OpenWalletButtons</a></code></dt>
+<dd><p>Apple Pay wallet button that creates One-Time Tokens (OTT) via Apple Pay.</p>
+<p>Provides a fully typed Apple Pay integration with Apple Pay-specific metadata
+and validates that the service configuration corresponds to an Apple Pay service.
+On <code>load()</code>, the button fetches the service configuration and raises an error via <code>onError</code>
+if the service type does not match Apple Pay.</p>
+</dd>
+<dt><a href="#GooglePayOpenWalletButton">GooglePayOpenWalletButton</a> ⇐ <code><a href="#OpenWalletButtons">OpenWalletButtons</a></code></dt>
+<dd><p>Google Pay wallet button that creates One-Time Tokens (OTT) via Google Pay.</p>
+<p>Provides a fully typed Google Pay integration with Google Pay-specific metadata
+and validates that the service configuration corresponds to a Google Pay service.
+On <code>load()</code>, the button fetches the service configuration and raises an error via <code>onError</code>
+if the service type does not match Google Pay.</p>
+</dd>
+<dt><a href="#OpenWalletButtons">OpenWalletButtons</a></dt>
+<dd><p>Abstract base class for Open Wallet buttons. <strong>Do not instantiate directly.</strong>
+Use <a href="#ApplePayOpenWalletButton">ApplePayOpenWalletButton</a> or <a href="#GooglePayOpenWalletButton">GooglePayOpenWalletButton</a> instead.</p>
+<p>Use one of the concrete implementations instead:</p>
+<ul>
+<li><a href="#ApplePayOpenWalletButton">ApplePayOpenWalletButton</a> for Apple Pay integration</li>
+<li><a href="#GooglePayOpenWalletButton">GooglePayOpenWalletButton</a> for Google Pay integration</li>
+</ul>
+<p>These subclasses inherit all event handlers and lifecycle methods documented below.</p>
+</dd>
+</dl>
+
+## Constants
+
+<dl>
+<dt><a href="#EVENT">EVENT</a> : <code>object</code></dt>
+<dd><p>List of available event names in the Open Wallet button lifecycle.</p>
+</dd>
+<dt><a href="#WALLET_TYPES">WALLET_TYPES</a> : <code>object</code></dt>
+<dd><p>Enum of available wallet types.</p>
+</dd>
+<dt><a href="#TOKEN_TYPE">TOKEN_TYPE</a> : <code>object</code></dt>
+<dd><p>Token types returned in the OTT (One-Time Token) creation response.</p>
+</dd>
+<dt><a href="#ERROR_OPERATION">ERROR_OPERATION</a> : <code>object</code></dt>
+<dd><p>Operations that can fail during the wallet lifecycle.
+Used in the <code>context.operation</code> field of <a href="#OnErrorEventData">OnErrorEventData</a>.</p>
+</dd>
+</dl>
+
+## Typedefs
+
+<dl>
+<dt><a href="#OnClickCallback">OnClickCallback</a> ⇒ <code>boolean</code> | <code>void</code> | <code>Promise.&lt;(boolean|void)&gt;</code></dt>
+<dd><p>Callback for onClick method.</p>
+</dd>
+<dt><a href="#OnSuccessCallback">OnSuccessCallback</a> : <code>function</code></dt>
+<dd><p>Callback for onSuccess method.</p>
+</dd>
+<dt><a href="#OnUnavailableCallback">OnUnavailableCallback</a> : <code>function</code></dt>
+<dd><p>Callback for onUnavailable method.</p>
+</dd>
+<dt><a href="#OnErrorCallback">OnErrorCallback</a> : <code>function</code></dt>
+<dd><p>Callback for onError method.</p>
+</dd>
+<dt><a href="#OnCancelCallback">OnCancelCallback</a> : <code>function</code></dt>
+<dd><p>Callback for onCancel method.</p>
+</dd>
+<dt><a href="#OnShippingAddressChangeCallback">OnShippingAddressChangeCallback</a> ⇒ <code><a href="#OnShippingAddressChangeEventResponse">OnShippingAddressChangeEventResponse</a></code> | <code><a href="#OnShippingAddressChangeEventResponse">Promise.&lt;OnShippingAddressChangeEventResponse&gt;</a></code></dt>
+<dd><p>Callback for onShippingAddressChange method.</p>
+</dd>
+<dt><a href="#OnShippingOptionsChangeCallback">OnShippingOptionsChangeCallback</a> ⇒ <code><a href="#OnShippingOptionChangeEventResponse">OnShippingOptionChangeEventResponse</a></code> | <code><a href="#OnShippingOptionChangeEventResponse">Promise.&lt;OnShippingOptionChangeEventResponse&gt;</a></code></dt>
+<dd><p>Callback for onShippingOptionsChange method.</p>
+</dd>
+</dl>
+
+## Interfaces
+
+<dl>
+<dt><a href="#ApplePayOpenWalletMeta">ApplePayOpenWalletMeta</a> : <code>object</code></dt>
+<dd><p>Interface for Apple Pay-specific metadata.</p>
+<p>For further information about ApplePay Capabilities refer to <a href="https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/4440085-applepaycapabilities">the documentation</a>.
+Apple will determine if the device has an ApplePay wallet available and at least one active payment.</p>
+</dd>
+<dt><a href="#GooglePayOpenWalletMeta">GooglePayOpenWalletMeta</a> : <code>object</code></dt>
+<dd><p>Interface for Google Pay-specific metadata.</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>
+<p>The merchant&#39;s <code>onClick</code> handler controls the payment flow via its return value:</p>
+<ul>
+<li>Return <code>void</code> / <code>undefined</code> to continue normally.</li>
+<li>Return <code>false</code> to abort the payment flow.</li>
+<li>Return a <code>Promise&lt;void&gt;</code> to defer the wallet sheet until the promise resolves.</li>
+<li>Return a <code>Promise&lt;boolean&gt;</code> — if it resolves to <code>false</code>, the flow is aborted.</li>
+<li>Throwing an error (sync or async) also aborts the flow.</li>
+</ul>
+</dd>
+<dt><a href="#OnCreateOTTSuccessfulEventData">OnCreateOTTSuccessfulEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnCreateOTTSuccessfulEventData.
+Emitted when the One-Time Token is successfully created.</p>
+</dd>
+<dt><a href="#OnCreateOTTErrorEventData">OnCreateOTTErrorEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnCreateOTTErrorEventData.
+Emitted when OTT creation fails. The error details are in the <code>data</code> payload.</p>
+</dd>
+<dt><a href="#OnUnavailableEventData">OnUnavailableEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnUnavailableEventData.
+Emitted when the wallet is not available on the current device or browser.</p>
+</dd>
+<dt><a href="#OnErrorEventData">OnErrorEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnErrorEventData.
+Emitted when an error occurs during wallet operation, including configuration issues, service type mismatches, and OTT creation failures.</p>
+</dd>
+<dt><a href="#OnLoadedEventData">OnLoadedEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnLoadedEventData.
+Emitted when the wallet button has been loaded and rendered in the DOM.
+No payload — the specific wallet type is determined by the concrete button class
+(<a href="#ApplePayOpenWalletButton">ApplePayOpenWalletButton</a> or <a href="#GooglePayOpenWalletButton">GooglePayOpenWalletButton</a>).</p>
+</dd>
+<dt><a href="#OnCancelEventData">OnCancelEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnCancelEventData.
+Emitted when the wallet checkout is cancelled or closed by the user. No payload data.</p>
+</dd>
+<dt><a href="#OnShippingAddressChangeEventData">OnShippingAddressChangeEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnShippingAddressChangeEventData.
+Emitted when the customer selects or updates their shipping address in the wallet payment sheet.
+This event is also emitted when the payment sheet first opens (INITIALIZE) with the initial shipping address, if present in the User&#39;s wallet.</p>
+<p>If no handler is registered for this event, the SDK auto-accepts with the current transaction data.</p>
+</dd>
+<dt><a href="#OnShippingAddressChangeEventResponse">OnShippingAddressChangeEventResponse</a> : <code>object</code></dt>
+<dd><p>Interface for OnShippingAddressChangeEventResponse.
+Returned by the merchant&#39;s <code>onShippingAddressChange</code> handler.</p>
+</dd>
+<dt><a href="#OnShippingOptionChangeEventData">OnShippingOptionChangeEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnShippingOptionChangeEventData.
+Emitted when the customer selects a shipping option in the wallet payment sheet.</p>
+<p>If no handler is registered for this event, the SDK auto-accepts with the current transaction data.</p>
+</dd>
+<dt><a href="#OnShippingOptionChangeEventResponse">OnShippingOptionChangeEventResponse</a> : <code>object</code></dt>
+<dd><p>Interface for OnShippingOptionChangeEventResponse.
+Returned by the merchant&#39;s <code>onShippingOptionsChange</code> handler.</p>
+</dd>
+<dt><a href="#IApplePayShippingOption">IApplePayShippingOption</a> : <code>object</code></dt>
+<dd><p>Interface for IApplePayShippingOption.
+Used for shipping options in Apple Pay wallets.</p>
+</dd>
+<dt><a href="#IGooglePayShippingOption">IGooglePayShippingOption</a> : <code>object</code></dt>
+<dd><p>Interface for IGooglePayShippingOption.
+Used for shipping options in Google Pay wallets.</p>
+</dd>
+</dl>
+
+<a name="ApplePayOpenWalletMeta" id="ApplePayOpenWalletMeta" href="#ApplePayOpenWalletMeta">&nbsp;</a>
+
+## ApplePayOpenWalletMeta : <code>object</code>
+Interface for Apple Pay-specific metadata.
+
+For further information about ApplePay Capabilities refer to [the documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/4440085-applepaycapabilities).
+Apple will determine if the device has an ApplePay wallet available and at least one active payment.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| amount | <code>number</code> | The payment amount. |
+| currency | <code>string</code> | The ISO 4217 currency code. |
+| country | <code>string</code> | The ISO 3166-1 alpha-2 country code. |
+| amount_label | <code>string</code> | Label shown next to the total amount (e.g. `'TOTAL'`). Used in the Apple Pay payment sheet. |
+| [request_shipping] | <code>boolean</code> | Enable shipping address collection in the Apple Pay sheet. |
+| [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. |
+| [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. |
+| [required_shipping_contact_fields] | <code>Array.&lt;(&#x27;email&#x27;\|&#x27;phone&#x27;\|&#x27;postalAddress&#x27;\|&#x27;name&#x27;)&gt;</code> | Shipping contact fields required to complete the transaction. Include `'postalAddress'` to show address fields in the Apple Pay sheet. Required handling of onShippingAddressChange callback. |
+| [supported_countries] | <code>Array.&lt;string&gt;</code> | List of countries where Apple Pay is supported by the merchant. |
+| [shipping_editing_mode] | <code>&#x27;available&#x27;</code> \| <code>&#x27;store\_pickup&#x27;</code> | `'available'` for editable shipping, `'store_pickup'` for non-editable. |
+| [style] | <code>object</code> | Styling configuration for the Apple Pay button. |
+| [style.button_type] | <code>ApplePayButtonType</code> | The type of Apple Pay button (e.g. `'buy'`, `'donate'`, `'plain'`). |
+| [style.button_style] | <code>ApplePayButtonStyle</code> | The style of the Apple Pay button (`'black'`, `'white'`, `'white-outline'`). |
+
+<a name="GooglePayOpenWalletMeta" id="GooglePayOpenWalletMeta" href="#GooglePayOpenWalletMeta">&nbsp;</a>
+
+## GooglePayOpenWalletMeta : <code>object</code>
+Interface for Google Pay-specific metadata.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| amount | <code>number</code> | The payment amount. |
+| currency | <code>string</code> | The ISO 4217 currency code. |
+| country | <code>string</code> | The ISO 3166-1 alpha-2 country code. |
+| [amount_label] | <code>string</code> | Label shown next to the total amount. |
+| [merchant_name] | <code>string</code> | Display name for the merchant in the Google Pay sheet. |
+| [request_shipping] | <code>boolean</code> | Enable shipping address collection. |
+| [shipping_options] | [<code>Array.&lt;IGooglePayShippingOption&gt;</code>](#IGooglePayShippingOption) | 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. |
+| [card_config] | <code>object</code> | Google Pay card configuration for custom auth methods, card networks, and tokenization. |
+| [style] | <code>object</code> | Styling configuration for the Google Pay button. |
+| [style.button_type] | <code>GooglePayButtonType</code> | The type of Google Pay button (`'book'`, `'buy'`, `'checkout'`, `'donate'`, `'order'`, `'pay'`, `'plain'`, `'subscribe'`). |
+| [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="OnClickEventData" id="OnClickEventData" href="#OnClickEventData">&nbsp;</a>
+
+## OnClickEventData : <code>object</code>
+Interface for OnClickEventData.
+Emitted when the wallet button is clicked.
+
+The merchant's `onClick` handler controls the payment flow via its return value:
+- Return `void` / `undefined` to continue normally.
+- Return `false` to abort the payment flow.
+- Return a `Promise<void>` to defer the wallet sheet until the promise resolves.
+- Return a `Promise<boolean>` — if it resolves to `false`, the flow is aborted.
+- Throwing an error (sync or async) also aborts the flow.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'onClick'`. |
+
+<a name="OnCreateOTTSuccessfulEventData" id="OnCreateOTTSuccessfulEventData" href="#OnCreateOTTSuccessfulEventData">&nbsp;</a>
+
+## OnCreateOTTSuccessfulEventData : <code>object</code>
+Interface for OnCreateOTTSuccessfulEventData.
+Emitted when the One-Time Token is successfully created.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'success'`. |
+| [data] | <code>object</code> | OTT success payload. |
+| data.token | <code>object</code> | The created OTT response. |
+| data.token.temp_token | <code>string</code> | The temporary one-time token string. |
+| data.token.token_type | [<code>TOKEN\_TYPE</code>](#TOKEN_TYPE) | The type of the token. `TOKEN_TYPE.CARD` for FPAN (Google Pay only), `TOKEN_TYPE.CARD_SCHEME_TOKEN` for DPAN (Apple Pay & Google Pay). |
+| data.amount | <code>number</code> | The payment amount. |
+| [data.shipping] | <code>object</code> | The shipping address and contact information, if provided. |
+| [data.shipping.method] | <code>string</code> | The shipping method. |
+| [data.shipping.options] | <code>Array.&lt;(IApplePayShippingOption\|IGooglePayShippingOption)&gt;</code> | The selected shipping options. |
+| [data.shipping.address_line1] | <code>string</code> | Shipping address line 1. |
+| [data.shipping.address_line2] | <code>string</code> | Shipping address line 2. |
+| [data.shipping.address_city] | <code>string</code> | Shipping address city. |
+| [data.shipping.address_postcode] | <code>string</code> | Shipping address postal code. |
+| [data.shipping.address_state] | <code>string</code> | Shipping address state or province. |
+| [data.shipping.address_country] | <code>string</code> | Shipping address country code. |
+| [data.shipping.address_company] | <code>string</code> | Shipping company name. |
+| [data.shipping.address_origin_postcode] | <code>string</code> | Origin postal code. |
+| [data.shipping.contact] | <code>object</code> | Shipping contact information. |
+| [data.shipping.contact.first_name] | <code>string</code> | Contact first name. |
+| [data.shipping.contact.last_name] | <code>string</code> | Contact last name. |
+| [data.shipping.contact.email] | <code>string</code> | Contact email address. |
+| [data.shipping.contact.phone] | <code>string</code> | Contact phone number. |
+| [data.shipping.contact.phone2] | <code>string</code> | Contact secondary phone number. |
+| [data.billing] | <code>object</code> | The billing address, if provided. |
+| data.billing.address_line1 | <code>string</code> | Billing address line 1. |
+| data.billing.address_line2 | <code>string</code> | Billing address line 2. |
+| data.billing.address_country | <code>string</code> | Billing address country code. |
+| data.billing.address_city | <code>string</code> | Billing address city. |
+| data.billing.address_postcode | <code>string</code> | Billing address postal code. |
+| data.billing.address_state | <code>string</code> | Billing address state or province. |
+
+<a name="OnCreateOTTErrorEventData" id="OnCreateOTTErrorEventData" href="#OnCreateOTTErrorEventData">&nbsp;</a>
+
+## OnCreateOTTErrorEventData : <code>object</code>
+Interface for OnCreateOTTErrorEventData.
+Emitted when OTT creation fails. The error details are in the `data` payload.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'error'`. |
+| [data] | <code>object</code> | Error details payload. |
+| [data.message] | <code>string</code> | Error message. |
+| [data.code] | <code>string</code> | Error code. |
+
+<a name="OnUnavailableEventData" id="OnUnavailableEventData" href="#OnUnavailableEventData">&nbsp;</a>
+
+## OnUnavailableEventData : <code>object</code>
+Interface for OnUnavailableEventData.
+Emitted when the wallet is not available on the current device or browser.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'unavailable'`. |
+| [data] | <code>object</code> | Unavailability details payload. |
+| data.reason | <code>string</code> | A human-readable reason why the wallet is unavailable. |
+| [data.details] | <code>object</code> | Additional details about the unavailability. |
+| data.details.service_id | <code>string</code> | The service ID that was checked. |
+
+<a name="OnErrorEventData" id="OnErrorEventData" href="#OnErrorEventData">&nbsp;</a>
+
+## OnErrorEventData : <code>object</code>
+Interface for OnErrorEventData.
+Emitted when an error occurs during wallet operation, including configuration issues, service type mismatches, and OTT creation failures.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'error'`. |
+| [data] | <code>object</code> | Error payload. |
+| data.error | <code>Error</code> | The Error object describing what went wrong. |
+| [data.context] | <code>object</code> | Context about the error. |
+| [data.context.operation] | [<code>ERROR\_OPERATION</code>](#ERROR_OPERATION) | The operation that failed. See [ERROR_OPERATION](#ERROR_OPERATION) enum for possible values. |
+
+<a name="OnLoadedEventData" id="OnLoadedEventData" href="#OnLoadedEventData">&nbsp;</a>
+
+## OnLoadedEventData : <code>object</code>
+Interface for OnLoadedEventData.
+Emitted when the wallet button has been loaded and rendered in the DOM.
+No payload — the specific wallet type is determined by the concrete button class
+([ApplePayOpenWalletButton](#ApplePayOpenWalletButton) or [GooglePayOpenWalletButton](#GooglePayOpenWalletButton)).
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'loaded'`. |
+
+<a name="OnCancelEventData" id="OnCancelEventData" href="#OnCancelEventData">&nbsp;</a>
+
+## OnCancelEventData : <code>object</code>
+Interface for OnCancelEventData.
+Emitted when the wallet checkout is cancelled or closed by the user. No payload data.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'checkoutClose'`. |
+
+<a name="OnShippingAddressChangeEventData" id="OnShippingAddressChangeEventData" href="#OnShippingAddressChangeEventData">&nbsp;</a>
+
+## OnShippingAddressChangeEventData : <code>object</code>
+Interface for OnShippingAddressChangeEventData.
+Emitted when the customer selects or updates their shipping address in the wallet payment sheet.
+This event is also emitted when the payment sheet first opens (INITIALIZE) with the initial shipping address, if present in the User's wallet.
+
+If no handler is registered for this event, the SDK auto-accepts with the current transaction data.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'onShippingAddressChange'`. |
+| [data] | <code>object</code> | Shipping address data. |
+| [data.address_city] | <code>string</code> | Shipping address city. |
+| [data.address_state] | <code>string</code> | Shipping address state. |
+| [data.address_postcode] | <code>string</code> | Shipping address postal code. |
+| [data.address_country] | <code>string</code> | Shipping address country code. |
+| [data.address_line1] | <code>string</code> | Apple Pay only - Shipping address line 1. |
+| [data.address_line2] | <code>string</code> | Apple Pay only - Shipping address line 2. |
+| [data.contact.phone] | <code>string</code> | Apple Pay only - Shipping contact phone. |
+| [data.contact.email] | <code>string</code> | Apple Pay only - Shipping contact email. |
+| [data.contact.first_name] | <code>string</code> | Apple Pay only - Shipping contact first name. |
+| [data.contact.last_name] | <code>string</code> | Apple Pay only - Shipping contact last name. |
+
+<a name="OnShippingAddressChangeEventResponse" id="OnShippingAddressChangeEventResponse" href="#OnShippingAddressChangeEventResponse">&nbsp;</a>
+
+## OnShippingAddressChangeEventResponse : <code>object</code>
+Interface for OnShippingAddressChangeEventResponse.
+Returned by the merchant's `onShippingAddressChange` handler.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [amount] | <code>number</code> | Updated payment amount based on the new shipping address. |
+| [shipping_options] | <code>Array.&lt;(IApplePayShippingOption\|IGooglePayShippingOption)&gt;</code> | Updated list of available shipping options. The first item is used as the default selected option. |
+| [error] | <code>object</code> | Error object to display in the wallet payment sheet if the address is invalid. |
+| error.code | <code>string</code> | Error code. Possible values: `'address_error'`, `'country_error'`, `'state_error'`, `'zip_error'`, `'shipping_contact_invalid'`, `'billing_contact_invalid'`. |
+| [error.field] | <code>string</code> | Apple Pay only - The specific field that caused the error. Possible values: `'phone'`, `'email'`, `'name'`, `'phonetic_name'`, `'address_lines'`, `'locality'`, `'postal_code'`, `'administrative_area'`, `'country'`, `'country_code'`. |
+| [error.message] | <code>string</code> | A human-readable error message to display to the customer. |
+
+<a name="OnShippingOptionChangeEventData" id="OnShippingOptionChangeEventData" href="#OnShippingOptionChangeEventData">&nbsp;</a>
+
+## OnShippingOptionChangeEventData : <code>object</code>
+Interface for OnShippingOptionChangeEventData.
+Emitted when the customer selects a shipping option in the wallet payment sheet.
+
+If no handler is registered for this event, the SDK auto-accepts with the current transaction data.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Always `'onShippingOptionsChange'`. |
+| [data] | <code>object</code> | Shipping option data. |
+| [data.shipping_option_id] | <code>string</code> | Selected shipping option ID. |
+| [data.label] | <code>string</code> | Selected shipping option label. |
+| [data.detail] | <code>string</code> | Selected shipping option detail. |
+| [data.amount] | <code>string</code> | Apple Pay only - Selected shipping option amount. |
+
+<a name="OnShippingOptionChangeEventResponse" id="OnShippingOptionChangeEventResponse" href="#OnShippingOptionChangeEventResponse">&nbsp;</a>
+
+## OnShippingOptionChangeEventResponse : <code>object</code>
+Interface for OnShippingOptionChangeEventResponse.
+Returned by the merchant's `onShippingOptionsChange` handler.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [amount] | <code>number</code> | Updated total payment amount based on the selected shipping option. |
+| [error] | <code>object</code> | Error object to display if the shipping option is invalid. |
+| error.code | <code>string</code> | Error code. Possible values: `'method_unavailable'`, `'store_unavailable'`. |
+| [error.message] | <code>string</code> | A human-readable error message. |
+
+<a name="IApplePayShippingOption" id="IApplePayShippingOption" href="#IApplePayShippingOption">&nbsp;</a>
+
+## IApplePayShippingOption : <code>object</code>
+Interface for IApplePayShippingOption.
+Used for shipping options in Apple Pay wallets.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| id | <code>string</code> | Unique identifier for the shipping option. |
+| label | <code>string</code> | Display name for the shipping option. |
+| amount | <code>number</code> | Shipping cost amount. |
+| [detail] | <code>string</code> | Optional description or detail text. |
+| [date_components_range] | <code>object</code> | Apple Pay only - Delivery date range estimate. |
+| [date_components_range.start_date_components] | <code>object</code> | Start date for the delivery estimate. |
+| [date_components_range.start_date_components.years] | <code>number</code> | Years from now. |
+| [date_components_range.start_date_components.months] | <code>number</code> | Months from now. |
+| [date_components_range.start_date_components.days] | <code>number</code> | Days from now. |
+| [date_components_range.start_date_components.hours] | <code>number</code> | Hours from now. |
+| [date_components_range.end_date_components] | <code>object</code> | End date for the delivery estimate. |
+| [date_components_range.end_date_components.years] | <code>number</code> | Years from now. |
+| [date_components_range.end_date_components.months] | <code>number</code> | Months from now. |
+| [date_components_range.end_date_components.days] | <code>number</code> | Days from now. |
+| [date_components_range.end_date_components.hours] | <code>number</code> | Hours from now. |
+
+<a name="IGooglePayShippingOption" id="IGooglePayShippingOption" href="#IGooglePayShippingOption">&nbsp;</a>
+
+## IGooglePayShippingOption : <code>object</code>
+Interface for IGooglePayShippingOption.
+Used for shipping options in Google Pay wallets.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| id | <code>string</code> | Unique identifier for the shipping option. |
+| label | <code>string</code> | Display name for the shipping option. |
+| [detail] | <code>string</code> | Optional description or detail text. |
+| [type] | <code>&#x27;ELECTRONIC&#x27;</code> \| <code>&#x27;GROUND&#x27;</code> \| <code>&#x27;NOT\_SHIPPED&#x27;</code> \| <code>&#x27;OVERNIGHT&#x27;</code> \| <code>&#x27;PICKUP&#x27;</code> \| <code>&#x27;PRIORITY&#x27;</code> \| <code>&#x27;SAME\_DAY&#x27;</code> | The shipping type. |
+
+<a name="ApplePayOpenWalletButton" id="ApplePayOpenWalletButton" href="#ApplePayOpenWalletButton">&nbsp;</a>
+
+## ApplePayOpenWalletButton ⇐ [<code>OpenWalletButtons</code>](#OpenWalletButtons)
+Apple Pay wallet button that creates One-Time Tokens (OTT) via Apple Pay.
+
+Provides a fully typed Apple Pay integration with Apple Pay-specific metadata
+and validates that the service configuration corresponds to an Apple Pay service.
+On `load()`, the button fetches the service configuration and raises an error via `onError`
+if the service type does not match Apple Pay.
+
+**Kind**: global class  
+**Extends**: [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+* [ApplePayOpenWalletButton](#ApplePayOpenWalletButton) ⇐ [<code>OpenWalletButtons</code>](#OpenWalletButtons)
+    * [new ApplePayOpenWalletButton(selector, publicKeyOrAccessToken, serviceId, meta)](#new_ApplePayOpenWalletButton_new)
+    * [.load()](#OpenWalletButtons+load)
+    * [.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)
+
+<a name="new_ApplePayOpenWalletButton_new" id="new_ApplePayOpenWalletButton_new" href="#new_ApplePayOpenWalletButton_new">&nbsp;</a>
+
+### new ApplePayOpenWalletButton(selector, publicKeyOrAccessToken, serviceId, meta)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| selector | <code>string</code> | CSS selector of the HTML element that will contain the Apple Pay button. |
+| publicKeyOrAccessToken | <code>string</code> | Public key or access token for API authentication. |
+| serviceId | <code>string</code> | The Apple Pay service ID configured in PayDock dashboard. |
+| meta | [<code>ApplePayOpenWalletMeta</code>](#ApplePayOpenWalletMeta) | Apple Pay-specific metadata (amount, currency, country, amount_label, store_name, style, apple_pay_capabilities, etc.). |
+
+**Example**  
+```js
+const button = new ApplePayOpenWalletButton(
+  '#wallet-container',
+  publicKeyOrAccessToken,
+  serviceId,
+  {
+    amount: 100,
+    currency: 'AUD',
+    country: 'AU',
+    amount_label: 'TOTAL',
+    store_name: 'My Store',
+    apple_pay_capabilities: ['credentials_available'],
+  },
+);
+button.setEnv('sandbox');
+button.onSuccess((data) => console.log('OTT:', data.token));
+button.onError((error) => console.error('Error:', error));
+button.load();
+```
+<a name="OpenWalletButtons+load" id="OpenWalletButtons+load" href="#OpenWalletButtons+load">&nbsp;</a>
+
+### applePayOpenWalletButton.load()
+Loads and initializes the wallet button based on the service configuration.
+This method fetches the wallet service configuration, validates that the service
+type matches the expected wallet, and creates the appropriate wallet service instance.
+Bear in mind that you must call this method after setting up all event handlers.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+**Example**  
+```js
+button.onClick((data) => { ... });
+button.onSuccess((data) => { ... });
+button.onError((error) => { ... });
+button.load();
+```
+<a name="OpenWalletButtons+setEnv" id="OpenWalletButtons+setEnv" href="#OpenWalletButtons+setEnv">&nbsp;</a>
+
+### applePayOpenWalletButton.setEnv(env, [alias])
+Current method can change environment. By default environment = sandbox.
+Also we can change domain alias for this environment. By default domain_alias = paydock.com
+Bear in mind that you must set an environment before calling `button.load()`.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| env | <code>string</code> | The target environment: `'sandbox'` or `'production'`. |
+| [alias] | <code>string</code> | Own domain alias. |
+
+**Example**  
+```js
+button.setEnv('production', 'paydock.com');
+```
+<a name="OpenWalletButtons+setMeta" id="OpenWalletButtons+setMeta" href="#OpenWalletButtons+setMeta">&nbsp;</a>
+
+### applePayOpenWalletButton.setMeta(meta)
+Updates the wallet metadata after initialization.
+Use this when order information changes (e.g. amount, currency) after the button has been rendered.
+Bear in mind that this must be called before the next payment attempt takes effect.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| meta | [<code>ApplePayOpenWalletMeta</code>](#ApplePayOpenWalletMeta) \| [<code>GooglePayOpenWalletMeta</code>](#GooglePayOpenWalletMeta) | The updated metadata object. The concrete type depends on the button class. |
+
+**Example**  
+```js
+button.setMeta({ ...meta, amount: 29.99 });
+```
+<a name="OpenWalletButtons+destroy" id="OpenWalletButtons+destroy" href="#OpenWalletButtons+destroy">&nbsp;</a>
+
+### applePayOpenWalletButton.destroy()
+Removes the wallet button from the DOM and cleans up resources.
+Call this method when the wallet button is no longer needed (e.g. navigating away from the payment page).
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+**Example**  
+```js
+button.destroy();
+```
+<a name="OpenWalletButtons+onClick" id="OpenWalletButtons+onClick" href="#OpenWalletButtons+onClick">&nbsp;</a>
+
+### applePayOpenWalletButton.onClick(handler)
+Registers a callback function to be invoked when the wallet button gets clicked.
+The handler controls the wallet payment flow via its return value:
+
+- Return `void` (or nothing) to continue the payment flow normally.
+- Return `false` to abort the payment flow.
+- Return a `Promise<void>` to defer the wallet sheet until the promise resolves.
+- Return a `Promise<boolean>` — if it resolves to `false`, the flow is aborted.
+- Throwing an error (sync or async) also aborts the flow.
+
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Note:** this callback may be called multiple times as the customer closes the payment
+checkout and re-clicks the button.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnClickCallback</code>](#OnClickCallback) | Function to be called when the wallet button is clicked. |
+
+**Example**  
+```js
+// Synchronous usage — continue normally
+button.onClick((event) => {
+  performValidationLogic();
+});
+```
+**Example**  
+```js
+// Synchronous abort — return false to cancel the payment
+button.onClick((event) => {
+  if (!isOrderValid()) return false;
+});
+```
+**Example**  
+```js
+// Asynchronous usage — defer wallet sheet until the promise resolves
+button.onClick(async (event) => {
+  await fetch('/validate-order').then(res => res.json());
+});
+```
+<a name="OpenWalletButtons+onSuccess" id="OpenWalletButtons+onSuccess" href="#OpenWalletButtons+onSuccess">&nbsp;</a>
+
+### applePayOpenWalletButton.onSuccess(handler)
+Registers a callback function to be invoked when the OTT (One-Time Token) creation was successful.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Important:** A handler is required. Do not perform thread blocking operations in callback such as `window.alert()` calls.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnSuccessCallback</code>](#OnSuccessCallback) | Function to be called when the OTT creation was successful. |
+
+**Example**  
+```js
+button.onSuccess((event) => {
+  console.log('OTT created:', event.data.token.temp_token);
+  console.log('Amount:', event.data.amount);
+});
+```
+**Example**  
+```js
+// Async handler
+button.onSuccess(async (event) => {
+  await submitTokenToServer(event.data.token.temp_token);
+});
+```
+<a name="OpenWalletButtons+onUnavailable" id="OpenWalletButtons+onUnavailable" href="#OpenWalletButtons+onUnavailable">&nbsp;</a>
+
+### applePayOpenWalletButton.onUnavailable(handler)
+Registers a callback function to be invoked when the wallet is not available in the current context.
+This can happen when the wallet service is not supported on the current device or browser.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnUnavailableCallback</code>](#OnUnavailableCallback) | Function to be called when the wallet is not available in the current context. |
+
+**Example**  
+```js
+button.onUnavailable((event) => {
+  console.log('Wallet not available:', event.data.reason);
+});
+```
+<a name="OpenWalletButtons+onError" id="OpenWalletButtons+onError" href="#OpenWalletButtons+onError">&nbsp;</a>
+
+### applePayOpenWalletButton.onError(handler)
+Registers a callback function to be invoked when an error occurs during wallet operation.
+This includes configuration issues, validation errors, and OTT creation failures.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnErrorCallback</code>](#OnErrorCallback) | Function to be called when the wallet has an error. |
+
+**Example**  
+```js
+button.onError((event) => {
+  console.error('Wallet error:', event.data.error.message);
+  console.log('Context:', event.data.context);
+});
+```
+<a name="OpenWalletButtons+onCancel" id="OpenWalletButtons+onCancel" href="#OpenWalletButtons+onCancel">&nbsp;</a>
+
+### applePayOpenWalletButton.onCancel(handler)
+Registers a callback function to be invoked when the wallet checkout is cancelled or closed by the user.
+This event is triggered when the user dismisses the wallet payment interface without completing the transaction.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnCancelCallback</code>](#OnCancelCallback) | Function to be called when the wallet checkout is cancelled. |
+
+**Example**  
+```js
+button.onCancel((event) => {
+  console.log('Wallet checkout cancelled', event);
+});
+```
+<a name="OpenWalletButtons+onLoaded" id="OpenWalletButtons+onLoaded" href="#OpenWalletButtons+onLoaded">&nbsp;</a>
+
+### applePayOpenWalletButton.onLoaded(handler)
+Registers a callback function to be invoked when the wallet button has been loaded and rendered in the DOM.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | <code>function</code> | Function to be called when the wallet button is loaded. |
+
+**Example**  
+```js
+button.onLoaded((event) => {
+  console.log('Wallet button loaded');
+});
+```
+<a name="OpenWalletButtons+onShippingAddressChange" id="OpenWalletButtons+onShippingAddressChange" href="#OpenWalletButtons+onShippingAddressChange">&nbsp;</a>
+
+### applePayOpenWalletButton.onShippingAddressChange(handler)
+Registers a callback for when the customer selects or updates their shipping address.
+Use this method to listen for shipping address selection or input from customer when shipping is enabled.
+The event handler should return updated payment information including the new amount and
+available shipping options based on the selected address.
+Both synchronous and asynchronous (async) handlers are supported.
+
+In case of an address validation error, include the `error` field in the response
+to display an appropriate error in the wallet payment sheet.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnShippingAddressChangeCallback</code>](#OnShippingAddressChangeCallback) | Function to be called when the shipping address data is updated. |
+
+**Example**  
+```js
+// Async handler
+button.onShippingAddressChange(async (data) => {
+  const response = await fetch('https://your-server.com/update-shipping-address', {
+    method: 'POST',
+    body: JSON.stringify(data),
+  });
+  const result = await response.json();
+  return {
+    amount: result.newAmount,
+    shipping_options: result.availableShippingOptions,
+  };
+});
+```
+**Example**  
+```js
+// Sync handler
+button.onShippingAddressChange((data) => {
+  return {
+    amount: calculateShipping(data.data.address_country),
+    shipping_options: getOptionsForCountry(data.data.address_country),
+  };
+});
+```
+<a name="OpenWalletButtons+onShippingOptionsChange" id="OpenWalletButtons+onShippingOptionsChange" href="#OpenWalletButtons+onShippingOptionsChange">&nbsp;</a>
+
+### applePayOpenWalletButton.onShippingOptionsChange(handler)
+Registers a callback for when the customer selects a shipping option.
+Use this method to listen for shipping option selection from customer when shipping is enabled.
+The event handler should return the updated payment amount based on the selected shipping option.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Kind**: instance method of [<code>ApplePayOpenWalletButton</code>](#ApplePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnShippingOptionsChangeCallback</code>](#OnShippingOptionsChangeCallback) | Function to be called when the shipping options data is updated. |
+
+**Example**  
+```js
+// Async handler
+button.onShippingOptionsChange(async (data) => {
+  const response = await fetch('https://your-server.com/update-shipping-option', {
+    method: 'POST',
+    body: JSON.stringify({ shipping_option_id: data.data.shipping_option_id }),
+  });
+  const result = await response.json();
+  return {
+    amount: result.newTotalAmount,
+  };
+});
+```
+**Example**  
+```js
+// Sync handler
+button.onShippingOptionsChange((data) => {
+  return {
+    amount: lookupShippingCost(data.data.shipping_option_id),
+  };
+});
+```
+<a name="GooglePayOpenWalletButton" id="GooglePayOpenWalletButton" href="#GooglePayOpenWalletButton">&nbsp;</a>
+
+## GooglePayOpenWalletButton ⇐ [<code>OpenWalletButtons</code>](#OpenWalletButtons)
+Google Pay wallet button that creates One-Time Tokens (OTT) via Google Pay.
+
+Provides a fully typed Google Pay integration with Google Pay-specific metadata
+and validates that the service configuration corresponds to a Google Pay service.
+On `load()`, the button fetches the service configuration and raises an error via `onError`
+if the service type does not match Google Pay.
+
+**Kind**: global class  
+**Extends**: [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+* [GooglePayOpenWalletButton](#GooglePayOpenWalletButton) ⇐ [<code>OpenWalletButtons</code>](#OpenWalletButtons)
+    * [new GooglePayOpenWalletButton(selector, publicKeyOrAccessToken, serviceId, meta)](#new_GooglePayOpenWalletButton_new)
+    * [.load()](#OpenWalletButtons+load)
+    * [.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)
+
+<a name="new_GooglePayOpenWalletButton_new" id="new_GooglePayOpenWalletButton_new" href="#new_GooglePayOpenWalletButton_new">&nbsp;</a>
+
+### new GooglePayOpenWalletButton(selector, publicKeyOrAccessToken, serviceId, meta)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| selector | <code>string</code> | CSS selector of the HTML element that will contain the Google Pay button. |
+| publicKeyOrAccessToken | <code>string</code> | Public key or access token for API authentication. |
+| serviceId | <code>string</code> | The Google Pay service ID configured in PayDock dashboard. |
+| meta | [<code>GooglePayOpenWalletMeta</code>](#GooglePayOpenWalletMeta) | Google Pay-specific metadata (amount, currency, country, card_config, merchant_name, style, etc.). |
+
+**Example**  
+```js
+const button = new GooglePayOpenWalletButton(
+  '#wallet-container',
+  publicKeyOrAccessToken,
+  serviceId,
+  {
+    amount: 100,
+    currency: 'AUD',
+    country: 'AU',
+    merchant_name: 'Your Store',
+  },
+);
+button.setEnv('sandbox');
+button.onSuccess((data) => console.log('OTT:', data.token));
+button.onError((error) => console.error('Error:', error));
+button.load();
+```
+<a name="OpenWalletButtons+load" id="OpenWalletButtons+load" href="#OpenWalletButtons+load">&nbsp;</a>
+
+### googlePayOpenWalletButton.load()
+Loads and initializes the wallet button based on the service configuration.
+This method fetches the wallet service configuration, validates that the service
+type matches the expected wallet, and creates the appropriate wallet service instance.
+Bear in mind that you must call this method after setting up all event handlers.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+**Example**  
+```js
+button.onClick((data) => { ... });
+button.onSuccess((data) => { ... });
+button.onError((error) => { ... });
+button.load();
+```
+<a name="OpenWalletButtons+setEnv" id="OpenWalletButtons+setEnv" href="#OpenWalletButtons+setEnv">&nbsp;</a>
+
+### googlePayOpenWalletButton.setEnv(env, [alias])
+Current method can change environment. By default environment = sandbox.
+Also we can change domain alias for this environment. By default domain_alias = paydock.com
+Bear in mind that you must set an environment before calling `button.load()`.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| env | <code>string</code> | The target environment: `'sandbox'` or `'production'`. |
+| [alias] | <code>string</code> | Own domain alias. |
+
+**Example**  
+```js
+button.setEnv('production', 'paydock.com');
+```
+<a name="OpenWalletButtons+setMeta" id="OpenWalletButtons+setMeta" href="#OpenWalletButtons+setMeta">&nbsp;</a>
+
+### googlePayOpenWalletButton.setMeta(meta)
+Updates the wallet metadata after initialization.
+Use this when order information changes (e.g. amount, currency) after the button has been rendered.
+Bear in mind that this must be called before the next payment attempt takes effect.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| meta | [<code>ApplePayOpenWalletMeta</code>](#ApplePayOpenWalletMeta) \| [<code>GooglePayOpenWalletMeta</code>](#GooglePayOpenWalletMeta) | The updated metadata object. The concrete type depends on the button class. |
+
+**Example**  
+```js
+button.setMeta({ ...meta, amount: 29.99 });
+```
+<a name="OpenWalletButtons+destroy" id="OpenWalletButtons+destroy" href="#OpenWalletButtons+destroy">&nbsp;</a>
+
+### googlePayOpenWalletButton.destroy()
+Removes the wallet button from the DOM and cleans up resources.
+Call this method when the wallet button is no longer needed (e.g. navigating away from the payment page).
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+**Example**  
+```js
+button.destroy();
+```
+<a name="OpenWalletButtons+onClick" id="OpenWalletButtons+onClick" href="#OpenWalletButtons+onClick">&nbsp;</a>
+
+### googlePayOpenWalletButton.onClick(handler)
+Registers a callback function to be invoked when the wallet button gets clicked.
+The handler controls the wallet payment flow via its return value:
+
+- Return `void` (or nothing) to continue the payment flow normally.
+- Return `false` to abort the payment flow.
+- Return a `Promise<void>` to defer the wallet sheet until the promise resolves.
+- Return a `Promise<boolean>` — if it resolves to `false`, the flow is aborted.
+- Throwing an error (sync or async) also aborts the flow.
+
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Note:** this callback may be called multiple times as the customer closes the payment
+checkout and re-clicks the button.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnClickCallback</code>](#OnClickCallback) | Function to be called when the wallet button is clicked. |
+
+**Example**  
+```js
+// Synchronous usage — continue normally
+button.onClick((event) => {
+  performValidationLogic();
+});
+```
+**Example**  
+```js
+// Synchronous abort — return false to cancel the payment
+button.onClick((event) => {
+  if (!isOrderValid()) return false;
+});
+```
+**Example**  
+```js
+// Asynchronous usage — defer wallet sheet until the promise resolves
+button.onClick(async (event) => {
+  await fetch('/validate-order').then(res => res.json());
+});
+```
+<a name="OpenWalletButtons+onSuccess" id="OpenWalletButtons+onSuccess" href="#OpenWalletButtons+onSuccess">&nbsp;</a>
+
+### googlePayOpenWalletButton.onSuccess(handler)
+Registers a callback function to be invoked when the OTT (One-Time Token) creation was successful.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Important:** A handler is required. Do not perform thread blocking operations in callback such as `window.alert()` calls.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnSuccessCallback</code>](#OnSuccessCallback) | Function to be called when the OTT creation was successful. |
+
+**Example**  
+```js
+button.onSuccess((event) => {
+  console.log('OTT created:', event.data.token.temp_token);
+  console.log('Amount:', event.data.amount);
+});
+```
+**Example**  
+```js
+// Async handler
+button.onSuccess(async (event) => {
+  await submitTokenToServer(event.data.token.temp_token);
+});
+```
+<a name="OpenWalletButtons+onUnavailable" id="OpenWalletButtons+onUnavailable" href="#OpenWalletButtons+onUnavailable">&nbsp;</a>
+
+### googlePayOpenWalletButton.onUnavailable(handler)
+Registers a callback function to be invoked when the wallet is not available in the current context.
+This can happen when the wallet service is not supported on the current device or browser.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnUnavailableCallback</code>](#OnUnavailableCallback) | Function to be called when the wallet is not available in the current context. |
+
+**Example**  
+```js
+button.onUnavailable((event) => {
+  console.log('Wallet not available:', event.data.reason);
+});
+```
+<a name="OpenWalletButtons+onError" id="OpenWalletButtons+onError" href="#OpenWalletButtons+onError">&nbsp;</a>
+
+### googlePayOpenWalletButton.onError(handler)
+Registers a callback function to be invoked when an error occurs during wallet operation.
+This includes configuration issues, validation errors, and OTT creation failures.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnErrorCallback</code>](#OnErrorCallback) | Function to be called when the wallet has an error. |
+
+**Example**  
+```js
+button.onError((event) => {
+  console.error('Wallet error:', event.data.error.message);
+  console.log('Context:', event.data.context);
+});
+```
+<a name="OpenWalletButtons+onCancel" id="OpenWalletButtons+onCancel" href="#OpenWalletButtons+onCancel">&nbsp;</a>
+
+### googlePayOpenWalletButton.onCancel(handler)
+Registers a callback function to be invoked when the wallet checkout is cancelled or closed by the user.
+This event is triggered when the user dismisses the wallet payment interface without completing the transaction.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnCancelCallback</code>](#OnCancelCallback) | Function to be called when the wallet checkout is cancelled. |
+
+**Example**  
+```js
+button.onCancel((event) => {
+  console.log('Wallet checkout cancelled', event);
+});
+```
+<a name="OpenWalletButtons+onLoaded" id="OpenWalletButtons+onLoaded" href="#OpenWalletButtons+onLoaded">&nbsp;</a>
+
+### googlePayOpenWalletButton.onLoaded(handler)
+Registers a callback function to be invoked when the wallet button has been loaded and rendered in the DOM.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | <code>function</code> | Function to be called when the wallet button is loaded. |
+
+**Example**  
+```js
+button.onLoaded((event) => {
+  console.log('Wallet button loaded');
+});
+```
+<a name="OpenWalletButtons+onShippingAddressChange" id="OpenWalletButtons+onShippingAddressChange" href="#OpenWalletButtons+onShippingAddressChange">&nbsp;</a>
+
+### googlePayOpenWalletButton.onShippingAddressChange(handler)
+Registers a callback for when the customer selects or updates their shipping address.
+Use this method to listen for shipping address selection or input from customer when shipping is enabled.
+The event handler should return updated payment information including the new amount and
+available shipping options based on the selected address.
+Both synchronous and asynchronous (async) handlers are supported.
+
+In case of an address validation error, include the `error` field in the response
+to display an appropriate error in the wallet payment sheet.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnShippingAddressChangeCallback</code>](#OnShippingAddressChangeCallback) | Function to be called when the shipping address data is updated. |
+
+**Example**  
+```js
+// Async handler
+button.onShippingAddressChange(async (data) => {
+  const response = await fetch('https://your-server.com/update-shipping-address', {
+    method: 'POST',
+    body: JSON.stringify(data),
+  });
+  const result = await response.json();
+  return {
+    amount: result.newAmount,
+    shipping_options: result.availableShippingOptions,
+  };
+});
+```
+**Example**  
+```js
+// Sync handler
+button.onShippingAddressChange((data) => {
+  return {
+    amount: calculateShipping(data.data.address_country),
+    shipping_options: getOptionsForCountry(data.data.address_country),
+  };
+});
+```
+<a name="OpenWalletButtons+onShippingOptionsChange" id="OpenWalletButtons+onShippingOptionsChange" href="#OpenWalletButtons+onShippingOptionsChange">&nbsp;</a>
+
+### googlePayOpenWalletButton.onShippingOptionsChange(handler)
+Registers a callback for when the customer selects a shipping option.
+Use this method to listen for shipping option selection from customer when shipping is enabled.
+The event handler should return the updated payment amount based on the selected shipping option.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Kind**: instance method of [<code>GooglePayOpenWalletButton</code>](#GooglePayOpenWalletButton)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnShippingOptionsChangeCallback</code>](#OnShippingOptionsChangeCallback) | Function to be called when the shipping options data is updated. |
+
+**Example**  
+```js
+// Async handler
+button.onShippingOptionsChange(async (data) => {
+  const response = await fetch('https://your-server.com/update-shipping-option', {
+    method: 'POST',
+    body: JSON.stringify({ shipping_option_id: data.data.shipping_option_id }),
+  });
+  const result = await response.json();
+  return {
+    amount: result.newTotalAmount,
+  };
+});
+```
+**Example**  
+```js
+// Sync handler
+button.onShippingOptionsChange((data) => {
+  return {
+    amount: lookupShippingCost(data.data.shipping_option_id),
+  };
+});
+```
+<a name="OpenWalletButtons" id="OpenWalletButtons" href="#OpenWalletButtons">&nbsp;</a>
+
+## *OpenWalletButtons*
+Abstract base class for Open Wallet buttons. **Do not instantiate directly.**
+Use [ApplePayOpenWalletButton](#ApplePayOpenWalletButton) or [GooglePayOpenWalletButton](#GooglePayOpenWalletButton) instead.
+
+Use one of the concrete implementations instead:
+- [ApplePayOpenWalletButton](#ApplePayOpenWalletButton) for Apple Pay integration
+- [GooglePayOpenWalletButton](#GooglePayOpenWalletButton) for Google Pay integration
+
+These subclasses inherit all event handlers and lifecycle methods documented below.
+
+**Kind**: global abstract class  
+
+* *[OpenWalletButtons](#OpenWalletButtons)*
+    * *[.load()](#OpenWalletButtons+load)*
+    * *[.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)*
+
+<a name="OpenWalletButtons+load" id="OpenWalletButtons+load" href="#OpenWalletButtons+load">&nbsp;</a>
+
+### *openWalletButtons.load()*
+Loads and initializes the wallet button based on the service configuration.
+This method fetches the wallet service configuration, validates that the service
+type matches the expected wallet, and creates the appropriate wallet service instance.
+Bear in mind that you must call this method after setting up all event handlers.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+**Example**  
+```js
+button.onClick((data) => { ... });
+button.onSuccess((data) => { ... });
+button.onError((error) => { ... });
+button.load();
+```
+<a name="OpenWalletButtons+setEnv" id="OpenWalletButtons+setEnv" href="#OpenWalletButtons+setEnv">&nbsp;</a>
+
+### *openWalletButtons.setEnv(env, [alias])*
+Current method can change environment. By default environment = sandbox.
+Also we can change domain alias for this environment. By default domain_alias = paydock.com
+Bear in mind that you must set an environment before calling `button.load()`.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| env | <code>string</code> | The target environment: `'sandbox'` or `'production'`. |
+| [alias] | <code>string</code> | Own domain alias. |
+
+**Example**  
+```js
+button.setEnv('production', 'paydock.com');
+```
+<a name="OpenWalletButtons+setMeta" id="OpenWalletButtons+setMeta" href="#OpenWalletButtons+setMeta">&nbsp;</a>
+
+### *openWalletButtons.setMeta(meta)*
+Updates the wallet metadata after initialization.
+Use this when order information changes (e.g. amount, currency) after the button has been rendered.
+Bear in mind that this must be called before the next payment attempt takes effect.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| meta | [<code>ApplePayOpenWalletMeta</code>](#ApplePayOpenWalletMeta) \| [<code>GooglePayOpenWalletMeta</code>](#GooglePayOpenWalletMeta) | The updated metadata object. The concrete type depends on the button class. |
+
+**Example**  
+```js
+button.setMeta({ ...meta, amount: 29.99 });
+```
+<a name="OpenWalletButtons+destroy" id="OpenWalletButtons+destroy" href="#OpenWalletButtons+destroy">&nbsp;</a>
+
+### *openWalletButtons.destroy()*
+Removes the wallet button from the DOM and cleans up resources.
+Call this method when the wallet button is no longer needed (e.g. navigating away from the payment page).
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+**Example**  
+```js
+button.destroy();
+```
+<a name="OpenWalletButtons+onClick" id="OpenWalletButtons+onClick" href="#OpenWalletButtons+onClick">&nbsp;</a>
+
+### *openWalletButtons.onClick(handler)*
+Registers a callback function to be invoked when the wallet button gets clicked.
+The handler controls the wallet payment flow via its return value:
+
+- Return `void` (or nothing) to continue the payment flow normally.
+- Return `false` to abort the payment flow.
+- Return a `Promise<void>` to defer the wallet sheet until the promise resolves.
+- Return a `Promise<boolean>` — if it resolves to `false`, the flow is aborted.
+- Throwing an error (sync or async) also aborts the flow.
+
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Note:** this callback may be called multiple times as the customer closes the payment
+checkout and re-clicks the button.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnClickCallback</code>](#OnClickCallback) | Function to be called when the wallet button is clicked. |
+
+**Example**  
+```js
+// Synchronous usage — continue normally
+button.onClick((event) => {
+  performValidationLogic();
+});
+```
+**Example**  
+```js
+// Synchronous abort — return false to cancel the payment
+button.onClick((event) => {
+  if (!isOrderValid()) return false;
+});
+```
+**Example**  
+```js
+// Asynchronous usage — defer wallet sheet until the promise resolves
+button.onClick(async (event) => {
+  await fetch('/validate-order').then(res => res.json());
+});
+```
+<a name="OpenWalletButtons+onSuccess" id="OpenWalletButtons+onSuccess" href="#OpenWalletButtons+onSuccess">&nbsp;</a>
+
+### *openWalletButtons.onSuccess(handler)*
+Registers a callback function to be invoked when the OTT (One-Time Token) creation was successful.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Important:** A handler is required. Do not perform thread blocking operations in callback such as `window.alert()` calls.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnSuccessCallback</code>](#OnSuccessCallback) | Function to be called when the OTT creation was successful. |
+
+**Example**  
+```js
+button.onSuccess((event) => {
+  console.log('OTT created:', event.data.token.temp_token);
+  console.log('Amount:', event.data.amount);
+});
+```
+**Example**  
+```js
+// Async handler
+button.onSuccess(async (event) => {
+  await submitTokenToServer(event.data.token.temp_token);
+});
+```
+<a name="OpenWalletButtons+onUnavailable" id="OpenWalletButtons+onUnavailable" href="#OpenWalletButtons+onUnavailable">&nbsp;</a>
+
+### *openWalletButtons.onUnavailable(handler)*
+Registers a callback function to be invoked when the wallet is not available in the current context.
+This can happen when the wallet service is not supported on the current device or browser.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnUnavailableCallback</code>](#OnUnavailableCallback) | Function to be called when the wallet is not available in the current context. |
+
+**Example**  
+```js
+button.onUnavailable((event) => {
+  console.log('Wallet not available:', event.data.reason);
+});
+```
+<a name="OpenWalletButtons+onError" id="OpenWalletButtons+onError" href="#OpenWalletButtons+onError">&nbsp;</a>
+
+### *openWalletButtons.onError(handler)*
+Registers a callback function to be invoked when an error occurs during wallet operation.
+This includes configuration issues, validation errors, and OTT creation failures.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnErrorCallback</code>](#OnErrorCallback) | Function to be called when the wallet has an error. |
+
+**Example**  
+```js
+button.onError((event) => {
+  console.error('Wallet error:', event.data.error.message);
+  console.log('Context:', event.data.context);
+});
+```
+<a name="OpenWalletButtons+onCancel" id="OpenWalletButtons+onCancel" href="#OpenWalletButtons+onCancel">&nbsp;</a>
+
+### *openWalletButtons.onCancel(handler)*
+Registers a callback function to be invoked when the wallet checkout is cancelled or closed by the user.
+This event is triggered when the user dismisses the wallet payment interface without completing the transaction.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnCancelCallback</code>](#OnCancelCallback) | Function to be called when the wallet checkout is cancelled. |
+
+**Example**  
+```js
+button.onCancel((event) => {
+  console.log('Wallet checkout cancelled', event);
+});
+```
+<a name="OpenWalletButtons+onLoaded" id="OpenWalletButtons+onLoaded" href="#OpenWalletButtons+onLoaded">&nbsp;</a>
+
+### *openWalletButtons.onLoaded(handler)*
+Registers a callback function to be invoked when the wallet button has been loaded and rendered in the DOM.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Error handling:** If the handler throws (sync or async), the error is logged and swallowed
+so that internal processing continues uninterrupted.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | <code>function</code> | Function to be called when the wallet button is loaded. |
+
+**Example**  
+```js
+button.onLoaded((event) => {
+  console.log('Wallet button loaded');
+});
+```
+<a name="OpenWalletButtons+onShippingAddressChange" id="OpenWalletButtons+onShippingAddressChange" href="#OpenWalletButtons+onShippingAddressChange">&nbsp;</a>
+
+### *openWalletButtons.onShippingAddressChange(handler)*
+Registers a callback for when the customer selects or updates their shipping address.
+Use this method to listen for shipping address selection or input from customer when shipping is enabled.
+The event handler should return updated payment information including the new amount and
+available shipping options based on the selected address.
+Both synchronous and asynchronous (async) handlers are supported.
+
+In case of an address validation error, include the `error` field in the response
+to display an appropriate error in the wallet payment sheet.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnShippingAddressChangeCallback</code>](#OnShippingAddressChangeCallback) | Function to be called when the shipping address data is updated. |
+
+**Example**  
+```js
+// Async handler
+button.onShippingAddressChange(async (data) => {
+  const response = await fetch('https://your-server.com/update-shipping-address', {
+    method: 'POST',
+    body: JSON.stringify(data),
+  });
+  const result = await response.json();
+  return {
+    amount: result.newAmount,
+    shipping_options: result.availableShippingOptions,
+  };
+});
+```
+**Example**  
+```js
+// Sync handler
+button.onShippingAddressChange((data) => {
+  return {
+    amount: calculateShipping(data.data.address_country),
+    shipping_options: getOptionsForCountry(data.data.address_country),
+  };
+});
+```
+<a name="OpenWalletButtons+onShippingOptionsChange" id="OpenWalletButtons+onShippingOptionsChange" href="#OpenWalletButtons+onShippingOptionsChange">&nbsp;</a>
+
+### *openWalletButtons.onShippingOptionsChange(handler)*
+Registers a callback for when the customer selects a shipping option.
+Use this method to listen for shipping option selection from customer when shipping is enabled.
+The event handler should return the updated payment amount based on the selected shipping option.
+Both synchronous and asynchronous (async) handlers are supported.
+
+**Kind**: instance method of [<code>OpenWalletButtons</code>](#OpenWalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | [<code>OnShippingOptionsChangeCallback</code>](#OnShippingOptionsChangeCallback) | Function to be called when the shipping options data is updated. |
+
+**Example**  
+```js
+// Async handler
+button.onShippingOptionsChange(async (data) => {
+  const response = await fetch('https://your-server.com/update-shipping-option', {
+    method: 'POST',
+    body: JSON.stringify({ shipping_option_id: data.data.shipping_option_id }),
+  });
+  const result = await response.json();
+  return {
+    amount: result.newTotalAmount,
+  };
+});
+```
+**Example**  
+```js
+// Sync handler
+button.onShippingOptionsChange((data) => {
+  return {
+    amount: lookupShippingCost(data.data.shipping_option_id),
+  };
+});
+```
+<a name="EVENT" id="EVENT" href="#EVENT">&nbsp;</a>
+
+## EVENT : <code>object</code>
+List of available event names in the Open Wallet button lifecycle.
+
+**Kind**: global constant  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| ON_CLICK | <code>string</code> | <code>&quot;onClick&quot;</code> | Emitted when the wallet button is clicked. |
+| SUCCESS | <code>string</code> | <code>&quot;success&quot;</code> | Emitted when OTT creation succeeds. |
+| UNAVAILABLE | <code>string</code> | <code>&quot;unavailable&quot;</code> | Emitted when the wallet is not available. |
+| ERROR | <code>string</code> | <code>&quot;error&quot;</code> | Emitted when an error occurs. |
+| LOADED | <code>string</code> | <code>&quot;loaded&quot;</code> | Emitted when the button is rendered. |
+| CHECKOUT_CLOSE | <code>string</code> | <code>&quot;checkoutClose&quot;</code> | Emitted when the wallet checkout is cancelled. |
+| ON_SHIPPING_ADDRESS_CHANGE | <code>string</code> | <code>&quot;onShippingAddressChange&quot;</code> | Emitted when shipping address changes. |
+| ON_SHIPPING_OPTIONS_CHANGE | <code>string</code> | <code>&quot;onShippingOptionsChange&quot;</code> | Emitted when shipping option changes. |
+
+<a name="WALLET_TYPES" id="WALLET_TYPES" href="#WALLET_TYPES">&nbsp;</a>
+
+## WALLET\_TYPES : <code>object</code>
+Enum of available wallet types.
+
+**Kind**: global constant  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| APPLE_PAY | <code>string</code> | <code>&quot;apple&quot;</code> | Apple Pay wallet. |
+| GOOGLE_PAY | <code>string</code> | <code>&quot;google&quot;</code> | Google Pay wallet. |
+
+<a name="TOKEN_TYPE" id="TOKEN_TYPE" href="#TOKEN_TYPE">&nbsp;</a>
+
+## TOKEN\_TYPE : <code>object</code>
+Token types returned in the OTT (One-Time Token) creation response.
+
+**Kind**: global constant  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| CARD | <code>string</code> | <code>&quot;card&quot;</code> | FPAN (Funding Primary Account Number). Available for Google Pay only. |
+| CARD_SCHEME_TOKEN | <code>string</code> | <code>&quot;card_scheme_token&quot;</code> | DPAN (Device Primary Account Number). Available for both Apple Pay and Google Pay. |
+
+<a name="ERROR_OPERATION" id="ERROR_OPERATION" href="#ERROR_OPERATION">&nbsp;</a>
+
+## ERROR\_OPERATION : <code>object</code>
+Operations that can fail during the wallet lifecycle.
+Used in the `context.operation` field of [OnErrorEventData](#OnErrorEventData).
+
+**Kind**: global constant  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| WALLET_OPERATION | <code>string</code> | <code>&quot;wallet_operation&quot;</code> | General wallet lifecycle operation (default). |
+| CONFIGURATION | <code>string</code> | <code>&quot;configuration&quot;</code> | Loading or validating the wallet service configuration (e.g. network fetch failure, card config validation). |
+| HANDLER_REGISTRATION | <code>string</code> | <code>&quot;handler_registration&quot;</code> | A required event handler was not registered before calling load(). |
+| SHIPPING_UPDATE | <code>string</code> | <code>&quot;shipping_update&quot;</code> | Processing a shipping address or shipping option update failed. |
+
+<a name="OnClickCallback" id="OnClickCallback" href="#OnClickCallback">&nbsp;</a>
+
+## OnClickCallback ⇒ <code>boolean</code> \| <code>void</code> \| <code>Promise.&lt;(boolean\|void)&gt;</code>
+Callback for onClick method.
+
+**Kind**: global typedef  
+**Returns**: <code>boolean</code> \| <code>void</code> \| <code>Promise.&lt;(boolean\|void)&gt;</code> - Return `false` to abort, or a Promise to defer.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | [<code>OnClickEventData</code>](#OnClickEventData) | The click event data. |
+
+<a name="OnSuccessCallback" id="OnSuccessCallback" href="#OnSuccessCallback">&nbsp;</a>
+
+## OnSuccessCallback : <code>function</code>
+Callback for onSuccess method.
+
+**Kind**: global typedef  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | [<code>OnCreateOTTSuccessfulEventData</code>](#OnCreateOTTSuccessfulEventData) | The OTT creation result including the token, amount, and address data. |
+
+<a name="OnUnavailableCallback" id="OnUnavailableCallback" href="#OnUnavailableCallback">&nbsp;</a>
+
+## OnUnavailableCallback : <code>function</code>
+Callback for onUnavailable method.
+
+**Kind**: global typedef  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | [<code>OnUnavailableEventData</code>](#OnUnavailableEventData) | Data describing why the wallet is unavailable. |
+
+<a name="OnErrorCallback" id="OnErrorCallback" href="#OnErrorCallback">&nbsp;</a>
+
+## OnErrorCallback : <code>function</code>
+Callback for onError method.
+
+**Kind**: global typedef  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | [<code>OnErrorEventData</code>](#OnErrorEventData) | The error event data including the Error object and context. |
+
+<a name="OnCancelCallback" id="OnCancelCallback" href="#OnCancelCallback">&nbsp;</a>
+
+## OnCancelCallback : <code>function</code>
+Callback for onCancel method.
+
+**Kind**: global typedef  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | [<code>OnCancelEventData</code>](#OnCancelEventData) | Data associated with the cancellation event. |
+
+<a name="OnShippingAddressChangeCallback" id="OnShippingAddressChangeCallback" href="#OnShippingAddressChangeCallback">&nbsp;</a>
+
+## OnShippingAddressChangeCallback ⇒ [<code>OnShippingAddressChangeEventResponse</code>](#OnShippingAddressChangeEventResponse) \| [<code>Promise.&lt;OnShippingAddressChangeEventResponse&gt;</code>](#OnShippingAddressChangeEventResponse)
+Callback for onShippingAddressChange method.
+
+**Kind**: global typedef  
+**Returns**: [<code>OnShippingAddressChangeEventResponse</code>](#OnShippingAddressChangeEventResponse) \| [<code>Promise.&lt;OnShippingAddressChangeEventResponse&gt;</code>](#OnShippingAddressChangeEventResponse) - Address update result containing updated amount, shipping options, and optional error.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | [<code>OnShippingAddressChangeEventData</code>](#OnShippingAddressChangeEventData) | The shipping address data from the wallet. |
+
+<a name="OnShippingOptionsChangeCallback" id="OnShippingOptionsChangeCallback" href="#OnShippingOptionsChangeCallback">&nbsp;</a>
+
+## OnShippingOptionsChangeCallback ⇒ [<code>OnShippingOptionChangeEventResponse</code>](#OnShippingOptionChangeEventResponse) \| [<code>Promise.&lt;OnShippingOptionChangeEventResponse&gt;</code>](#OnShippingOptionChangeEventResponse)
+Callback for onShippingOptionsChange method.
+
+**Kind**: global typedef  
+**Returns**: [<code>OnShippingOptionChangeEventResponse</code>](#OnShippingOptionChangeEventResponse) \| [<code>Promise.&lt;OnShippingOptionChangeEventResponse&gt;</code>](#OnShippingOptionChangeEventResponse) - Shipping options update result containing the updated amount.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| data | [<code>OnShippingOptionChangeEventData</code>](#OnShippingOptionChangeEventData) | The selected shipping option data. |
+