npm - @paydock/client-sdk - Versions diffs - 1.139.0 → 1.140.0-beta - Mend

@paydock/client-sdk 1.139.0 → 1.140.0-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (73) hide show

package/README.md CHANGED Viewed

@@ -5462,6 +5462,2579 @@ Callback for onError method.
 | data | [<code>OnErrorEventData</code>](#OnErrorEventData) |
+## Open Wallet Buttons
+You can find description of all methods and parameters [here](https://www.npmjs.com/package/@paydock/client-sdk#open-wallet-buttons-simple-example)
+Open Wallet Buttons provide a next-generation approach to integrating E-Wallets into your checkout with improved event handling and more granular control over wallet interactions.
+Each wallet type has its own dedicated class with fully typed metadata:
+- [ApplePayOpenWalletButton](#ApplePayOpenWalletButton) - for Apple Pay integration
+- [GooglePayOpenWalletButton](#GooglePayOpenWalletButton) - for Google Pay integration
+On `load()`, each button fetches the service configuration from PayDock and validates that the service type matches the expected wallet. If there is a mismatch (e.g. using an Apple Pay service ID with `GooglePayOpenWalletButton`), an error will be raised via the `onError` callback.
+If available in your client environment, you will display a simple button that upon clicking it the user will follow the standard flow for the appropriate Wallet. If not available an event will be raised and no button will be displayed.
+## Apple Pay Open Wallet Button
+### Container
+```html
+<div id="widget"></div>
+```
+You must create a container for the Open Wallet Button. Inside this tag, the button will be initialized.
+Before initializing the button, you must configure your Apple Pay wallet service through the PayDock dashboard and obtain the service ID that will be used to load the button configuration.
+### Initialization
+```javascript
+let button = new paydock.ApplePayOpenWalletButton(
+    "#widget",
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: "AUD",
+        country: "AU",
+        amount_label: "TOTAL",
+        store_name: "My Store",
+        apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    }
+);
+button.load();
+```
+```javascript
+// ES2015 | TypeScript
+import { ApplePayOpenWalletButton } from '@paydock/client-sdk';
+var button = new ApplePayOpenWalletButton(
+    '#widget',
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: 'AUD',
+        country: 'AU',
+        amount_label: 'TOTAL',
+        store_name: 'My Store',
+    }
+);
+button.load();
+```
+### Constructor Parameters
+The ApplePayOpenWalletButton constructor accepts the following parameters:
+1. **selector** (string): CSS selector for the container element
+2. **publicKeyOrAccessToken** (string): Your PayDock public key or access token
+3. **serviceId** (string): The Apple Pay service ID configured in PayDock dashboard
+4. **meta** (ApplePayOpenWalletMeta): Apple Pay-specific configuration object
+> **Note:** Required meta fields (`amount`, `currency`, `country`, `amount_label`, `store_name`) are validated automatically by the `ApplePayOpenWalletButton` class. You do not need to specify them manually.
+### Setting environment
+Current method can change environment. By default environment = sandbox.
+Bear in mind that you must set an environment before calling `button.load()`.
+```javascript
+button.setEnv('sandbox');
+```
+### Full Apple Pay example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Apple Pay with Open Wallets</title>
+</head>
+<body>
+    <h2>Payment using PayDock Apple Pay Open Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.ApplePayOpenWalletButton(
+        "#widget",
+        publicKeyOrAccessToken,
+        serviceId,
+        {
+            amount: 100,
+            currency: "AUD",
+            country: "AU",
+            amount_label: "TOTAL",
+            store_name: "My Store",
+            request_shipping: true,
+            request_payer_name: true,
+            request_payer_email: true,
+            request_payer_phone: true,
+            show_billing_address: true,
+            style: {
+                button_type: 'buy',
+                button_style: 'black'
+            },
+            shipping_options: [
+                {
+                    id: "standard",
+                    label: "Standard Shipping",
+                    detail: "Arrives in 5 to 7 days",
+                    amount: 5.00,
+                    date_components_range: {
+                        start_date_components: {
+                            years: 0,
+                            months: 0,
+                            days: 5,
+                            hours: 0,
+                        },
+                        end_date_components: {
+                            years: 0,
+                            months: 0,
+                            days: 7,
+                            hours: 0,
+                        }
+                    }
+                },
+                {
+                    id: "express",
+                    label: "Express Shipping",
+                    detail: "Arrives in 1 to 2 days",
+                    amount: 15.00,
+                    date_components_range: {
+                        start_date_components: {
+                            years: 0,
+                            months: 0,
+                            days: 1,
+                            hours: 0,
+                        },
+                        end_date_components: {
+                            years: 0,
+                            months: 0,
+                            days: 2,
+                            hours: 0,
+                        }
+                    }
+                }
+            ],
+            apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable']
+        }
+    );
+    button.setEnv('sandbox');
+    button.onUnavailable((data) => {
+        console.log("Apple Pay not available:", data);
+        // Show alternative payment methods
+    });
+    button.onClick((data) => {
+        console.log("Apple Pay button clicked");
+        // Perform pre-payment validation
+    });
+    button.onSuccess((data) => {
+        console.log("Payment successful:", data);
+        // Process the OTT token on your backend
+        processPayment(data.token);
+    });
+    button.onError((data) => {
+        console.error("Payment error:", data);
+        // Handle error appropriately
+    });
+    button.onCancel((data) => {
+        console.log("Payment cancelled");
+        // Handle cancellation
+    });
+    button.onShippingAddressChange(async (addressData) => {
+        // Update shipping costs based on address
+        const response = await updateShippingCosts(addressData);
+        return {
+            amount: response.newAmount,
+            shipping_options: response.shippingOptions
+        };
+    });
+    button.onShippingOptionsChange(async (optionData) => {
+        // Update total based on selected shipping option
+        const response = await updateTotal(optionData);
+        return {
+            amount: response.newAmount
+        };
+    });
+    button.load();
+    async function updateShippingCosts(addressData) {
+        // Your shipping calculation logic based on address
+        const baseAmount = 100;
+        const updatedShippingOptions = [
+            {
+                id: "updated-standard",
+                label: "Updated Standard Shipping",
+                detail: "Based on your location",
+                amount: 8.00
+            },
+            {
+                id: "updated-express",
+                label: "Updated Express Shipping",
+                detail: "Fast delivery to your area",
+                amount: 18.00
+            }
+        ];
+        return {
+            newAmount: baseAmount + updatedShippingOptions[0].amount,
+            shippingOptions: updatedShippingOptions
+        };
+    }
+    async function updateTotal(optionData) {
+        // Your total calculation logic
+        const baseAmount = 100;
+        const shippingAmount = optionData.amount || optionData.data?.amount;
+        return {
+            newAmount: baseAmount + shippingAmount
+        };
+    }
+    function processPayment(ottToken) {
+        // Send OTT token to your backend for payment processing
+        fetch('/api/process-payment', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ott_token: ottToken })
+        });
+    }
+</script>
+</html>
+```
+### Apple Pay with Shipping
+For Apple Pay with shipping enabled:
+```javascript
+let button = new paydock.ApplePayOpenWalletButton(
+    "#widget",
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: "AUD",
+        country: "AU",
+        amount_label: "TOTAL",
+        store_name: "My Store",
+        request_shipping: true,
+        shipping_editing_mode: 'available',
+        required_shipping_contact_fields: [
+            'postalAddress',
+            'name',
+            'phone',
+            'email',
+        ],
+        shipping_options: [
+            {
+                id: "standard",
+                label: "Standard Shipping",
+                detail: "5-7 business days",
+                amount: 5.00
+            },
+            {
+                id: "express",
+                label: "Express Shipping",
+                detail: "1-2 business days",
+                amount: 15.00
+            }
+        ],
+        apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable']
+    }
+);
+button.load();
+```
+When supporting shipping, the methods `onShippingAddressChange` and `onShippingOptionsChange` are required to update the shipping address and options.
+```javascript
+button.onShippingAddressChange(async function(data) {
+    console.log("Shipping address has been updated", data);
+    // Call your backend to recalculate shipping
+    return {
+        amount: newAmount,
+        shipping_options: updatedShippingOptions
+    };
+});
+button.onShippingOptionsChange(async function(data) {
+    console.log("Shipping option selected", data);
+    // Update total based on selected shipping option
+    return {
+        amount: newTotalAmount
+    };
+});
+```
+### Supported Shipping Cases
+#### Injected Shipping Address, non-editable by the customer
+This is the case where the shipping address is injected by the merchant and is not editable by the customer. The customer can only select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'store_pickup'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'store_pickup',
+    required_shipping_contact_fields: [
+        'postalAddress',
+        'name',
+        'phone',
+        'email',
+    ],
+    shipping: {
+        amount: 5,
+        address_line1: "Address Line 1",
+        address_city: "Test Locality",
+        address_state: "NSW",
+        address_country: "Australia",
+        address_country_code: "AU",
+        address_postcode: "3000",
+        contact: {
+            phone: "+61400245562",
+            email: "test@example.com",
+            first_name: "QA",
+            last_name: "QA",
+        },
+        options: [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+            }
+        ],
+    },
+}
+```
+#### Injected Shipping Address, editable by the customer
+This is the case where the shipping address is injected by the merchant and is editable by the customer. The customer can edit the shipping address and select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'available'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'available',
+    required_shipping_contact_fields: [
+        'postalAddress',
+        'name',
+        'phone',
+        'email',
+    ],
+    shipping: {
+        amount: 5,
+        address_line1: "Address Line 1",
+        address_city: "Test Locality",
+        address_state: "NSW",
+        address_country: "Australia",
+        address_country_code: "AU",
+        address_postcode: "3000",
+        contact: {
+            phone: "+61400245562",
+            email: "test@example.com",
+            first_name: "QA",
+            last_name: "QA",
+        },
+        options: [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+            }
+        ],
+    },
+}
+```
+#### Shipping address editable by the customer (no pre-filled address)
+This is the case where the shipping address is not injected by the merchant and is editable by the customer. The customer can edit the shipping address and select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'available'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'available',
+    required_shipping_contact_fields: [
+        'postalAddress',
+        'name',
+        'phone',
+        'email',
+    ],
+}
+```
+#### No shipping address
+This is the case where no shipping address is required at all in the popup (e.g., digital goods, services, or virtual products, or Shipping Address collected separately by the merchant). The "Send to" UI field will not be shown in the Apple Pay sheet, it will be hidden.
+**Important:**
+- No shipping address should be provided in the meta object.
+- Shipping address could be provided in the initial POST `/v1/charges/wallet` endpoint, if collected previously.
+The required meta parameters for this case are:
+- `required_shipping_contact_fields`: Only include contact fields if needed (phone, email), but NOT `postalAddress`.
+```javascript
+meta: {
+    amount_label: "TOTAL",
+    country: "AU",
+    currency: "AUD",
+    amount: 10,
+    shipping_editing_mode: "available",
+    required_shipping_contact_fields: ["phone", "email"],
+    apple_pay_capabilities: ["credentials_available", "credentials_status_unknown", "credentials_unavailable"]
+}
+```
+## Google Pay Open Wallet Button
+### Initialization
+```javascript
+let button = new paydock.GooglePayOpenWalletButton(
+    "#widget",
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: "AUD",
+        country: "AU",
+        merchant_name: "Your Store",
+    }
+);
+button.load();
+```
+```javascript
+// ES2015 | TypeScript
+import { GooglePayOpenWalletButton } from '@paydock/client-sdk';
+var button = new GooglePayOpenWalletButton(
+    '#widget',
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: 'AUD',
+        country: 'AU',
+        merchant_name: 'Your Store',
+    }
+);
+button.load();
+```
+### Constructor Parameters
+The GooglePayOpenWalletButton constructor accepts the following parameters:
+1. **selector** (string): CSS selector for the container element
+2. **publicKeyOrAccessToken** (string): Your PayDock public key or access token
+3. **serviceId** (string): The Google Pay service ID configured in PayDock dashboard
+4. **meta** (GooglePayOpenWalletMeta): Google Pay-specific configuration object
+> **Note:** Required meta fields (`amount`, `currency`, `country`) are validated automatically by the `GooglePayOpenWalletButton` class. You do not need to specify them manually.
+### Full Google Pay Example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Google Pay with Open Wallets</title>
+</head>
+<body>
+    <h2>Payment using PayDock Google Pay Open Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.GooglePayOpenWalletButton(
+        "#widget",
+        publicKeyOrAccessToken,
+        serviceId,
+        {
+            amount: 100,
+            currency: "AUD",
+            country: "AU",
+            amount_label: "Total",
+            request_shipping: true,
+            show_billing_address: true,
+            merchant_name: 'Test Merchant',
+            style: {
+                button_type: 'buy',
+                button_color: 'default',
+                button_size_mode: 'fill'
+            },
+            shipping_options: [
+                {
+                    id: "standard",
+                    label: "Standard Shipping",
+                    detail: "Arrives in 5 to 7 days",
+                    amount: 5.00,
+                    type: "ELECTRONIC"
+                },
+                {
+                    id: "express",
+                    label: "Express Shipping",
+                    detail: "Arrives in 1 to 2 days",
+                    amount: 15.00,
+                    type: "PICKUP"
+                }
+            ]
+        }
+    );
+    button.setEnv('sandbox');
+    // Required handlers
+    button.onSuccess((data) => {
+        console.log("Payment successful:", data);
+        processPayment(data.token);
+    });
+    button.onShippingAddressChange(async (addressData) => {
+        const response = await updateShippingCosts(addressData);
+        return {
+            amount: response.newAmount,
+            shipping_options: response.shippingOptions
+        };
+    });
+    button.onShippingOptionsChange(async (optionData) => {
+        const response = await updateTotal(optionData);
+        return {
+            amount: response.newAmount
+        };
+    });
+    // Optional handlers
+    button.onUnavailable((data) => {
+        console.log("Google Pay not available:", data);
+        // Show alternative payment methods
+    });
+    button.onError((data) => {
+        console.error("Payment error:", data);
+        // Handle error appropriately
+    });
+    button.onCancel((data) => {
+        console.log("Payment cancelled");
+        // Handle cancellation
+    });
+    button.onClick((data) => {
+        console.log("Google Pay button clicked");
+        // Perform pre-payment validation
+    });
+    button.load();
+    // Helper functions
+    async function updateShippingCosts(addressData) {
+        const baseAmount = 100;
+        const updatedShippingOptions = [
+            {
+                id: "updated-standard",
+                label: "Updated Standard Shipping",
+                detail: "Based on your location",
+                amount: 8.00,
+                type: "ELECTRONIC"
+            },
+            {
+                id: "updated-express",
+                label: "Updated Express Shipping",
+                detail: "Fast delivery to your area",
+                amount: 18.00,
+                type: "PICKUP"
+            }
+        ];
+        return {
+            newAmount: baseAmount + updatedShippingOptions[0].amount,
+            shippingOptions: updatedShippingOptions
+        };
+    }
+    async function updateTotal(optionData) {
+        const baseAmount = 100;
+        const shippingAmount = optionData.amount || optionData.data?.amount;
+        return {
+            newAmount: baseAmount + shippingAmount
+        };
+    }
+    function processPayment(ottToken) {
+        fetch('/api/process-payment', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ott_token: ottToken })
+        });
+    }
+</script>
+</html>
+```
+## Common API
+Both `ApplePayOpenWalletButton` and `GooglePayOpenWalletButton` share the same event handler API inherited from the base class.
+### 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.
+```javascript
+button.onUnavailable((data) => console.log("No wallet button available", data));
+```
+### 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`:
+```javascript
+// This will raise an error if the service ID does not correspond to a Google Pay service
+let button = new paydock.GooglePayOpenWalletButton(
+    "#widget",
+    publicKeyOrAccessToken,
+    applePayServiceId, // Wrong! This is an Apple Pay service ID
+    meta
+);
+button.onError((data) => {
+    // Error: Service configuration type 'ApplePay' does not match expected wallet type 'google'.
+    console.error(data.error.message);
+});
+button.load();
+```
+### Performing actions when the wallet button is clicked
+You can perform validations or actions when the user clicks on the wallet button. The callback supports both synchronous and asynchronous operations using the `attachResult` method.
+```javascript
+// Synchronous example
+button.onClick((data) => {
+    console.log("Perform actions on button click");
+    // Perform validation logic
+    // Optionally use attachResult to control flow
+    data.attachResult(true); // Continue with payment
+    // data.attachResult(false); // Halt payment
+});
+// Asynchronous example
+button.onClick((data) => {
+    // Attach a Promise to control the wallet flow
+    data.attachResult(
+        fetch('/api/validate-order')
+            .then(response => response.json())
+            .then(result => {
+                if (!result.valid) {
+                    throw new Error('Order validation failed');
+                }
+                return result;
+            })
+    );
+});
+```
+### Handling successful OTT creation
+When the One Time Token (OTT) is successfully created, the onSuccess callback will be called with the token data. **This callback is required** - if no handler is provided, an error will be thrown.
+```javascript
+button.onSuccess((data) => {
+    console.log("OTT created successfully:", data.token);
+    console.log("Amount:", data.amount);
+    console.log("Shipping:", data.shipping);
+    console.log("Billing:", data.billing);
+    // Use the OTT token to complete payment on your backend
+    fetch('/api/process-payment', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ott_token: data.token })
+    });
+});
+```
+**Important**: The `onSuccess` event handler is mandatory. Not providing one will result in an error.
+### Updating meta after initialization
+If the screen where the button is rendered allows for cart/amount changes, call `setMeta` method to update the meta information. The `setMeta` method is fully typed for each wallet:
+```javascript
+// For Apple Pay - accepts ApplePayOpenWalletMeta
+applePayButton.setMeta({ ...meta, amount: 29.99, amount_label: 'NEW TOTAL' });
+// For Google Pay - accepts GooglePayOpenWalletMeta
+googlePayButton.setMeta({ ...meta, amount: 29.99, merchant_name: 'Updated Store' });
+```
+### Handling errors
+Register a callback function to handle errors that occur during wallet operations, including service type mismatches.
+```javascript
+button.onError((data) => {
+    console.error("Open Wallet error:", data.error);
+    console.log("Error context:", data.context);
+    // Show user-friendly error message
+    showErrorMessage("Payment initialization failed. Please try again.");
+});
+```
+### Handling checkout cancellation
+When the user cancels or closes the wallet payment interface, you can perform cleanup operations.
+```javascript
+button.onCancel((data) => {
+    console.log("Wallet checkout cancelled", data);
+    // Perform cleanup or redirect user
+    window.location.href = '/checkout';
+});
+```
+### Cleaning up
+Remove the wallet button from the DOM when it is no longer needed:
+```javascript
+button.destroy();
+```
+### Events
+The above events can be used in a more generic way via the `eventEmitter.subscribe` method internally, but the recommended approach is to use the dedicated event handler methods provided by the button classes.
+**Available Event Handler Methods:**
+- `onClick(handler)` - Button click events (supports attachResult for flow control)
+- `onSuccess(handler)` - **Required** - OTT creation success events
+- `onUnavailable(handler)` - Wallet unavailable events (supports Promise pattern)
+- `onError(handler)` - Error events (supports Promise pattern)
+- `onCancel(handler)` - Checkout cancellation events (supports Promise pattern)
+- `onLoaded(handler)` - Button loaded/rendered events
+- `onShippingAddressChange(handler)` - **Required for shipping** - Address change events
+- `onShippingOptionsChange(handler)` - **Required for shipping options** - Option change events
+**Event Handler Patterns:**
+```javascript
+// Required handlers (will throw error if not provided)
+button.onSuccess(handler);  // Always required
+button.onShippingAddressChange(handler);  // Required when shipping enabled
+button.onShippingOptionsChange(handler);  // Required when shipping options provided
+// Optional handlers with Promise support
+button.onUnavailable(handler);  // or await button.onUnavailable()
+button.onError(handler);        // or await button.onError()
+button.onCancel(handler);       // or await button.onCancel()
+// Click handler with flow control
+button.onClick(handler);  // Use data.attachResult() for async operations
+// Loaded handler
+button.onLoaded(handler);  // Notified when button renders
+```
+### Apple Pay-Specific Meta Properties
+A full description of the [ApplePayOpenWalletMeta](#ApplePayOpenWalletMeta) properties:
+**Required:**
+- `amount`: The payment amount (number)
+- `currency`: The currency code (string, e.g., "AUD")
+- `country`: The country code (string, e.g., "AU")
+- `amount_label`: Label for the total amount (string)
+- `store_name`: Merchant store name (string)
+**Optional:**
+- `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
+- `merchant_capabilities?: string[]`: Merchant capabilities
+- `supported_networks?: string[]`: Supported payment networks
+- `required_billing_contact_fields?: string[]`: Required billing contact fields
+- `required_shipping_contact_fields?: string[]`: Required shipping contact fields
+- `supported_countries?: string[]`: Supported countries
+- `shipping_editing_mode?: 'available' | 'store_pickup'`: Shipping address editing mode
+- `style?: { button_type?: ApplePayButtonType, button_style?: ApplePayButtonStyle }`: Button styling
+### Google Pay-Specific Meta Properties
+A full description of the [GooglePayOpenWalletMeta](#GooglePayOpenWalletMeta) properties:
+**Required:**
+- `amount`: The payment amount (number)
+- `currency`: The currency code (string, e.g., "AUD")
+- `country`: The country code (string, e.g., "AU")
+**Optional:**
+- `amount_label?: string`: Label for the total amount
+- `merchant_name?: string`: Display name for the merchant
+- `request_shipping?: boolean`: Enable shipping address collection
+- `shipping_options?: IGooglePayShippingOption[]`: Array of shipping options
+- `show_billing_address?: boolean`: Show billing address fields
+- `card_config?: GooglePayCardConfig`: Card configuration (auth methods, networks, tokenization)
+- `style?: { button_type?: GooglePayButtonType, button_color?: GooglePayButtonColor, button_size_mode?: GooglePayButtonSizeMode }`: Button styling
+### Shipping Options Format
+```javascript
+shipping_options: [
+    {
+        id: "option_id",           // Unique identifier (string)
+        label: "Option Name",      // Display name (string)
+        detail: "Description",     // Optional description (string)
+        amount: 10.00,            // Shipping cost as number
+        date_components_range: {   // Optional: delivery date range (Apple Pay only)
+            start_date_components: {
+                years: 0,
+                months: 0,
+                days: 5,
+                hours: 0,
+            },
+            end_date_components: {
+                years: 0,
+                months: 0,
+                days: 10,
+                hours: 0,
+            }
+        }
+    }
+]
+```
+**Important**:
+- `amount` should be a **number**, not a string
+- `date_components_range` is optional but provides delivery estimates (Apple Pay only)
+- Updated shipping options returned from event handlers don't require `date_components_range`
+### Environment Setup
+```javascript
+// Always set environment before loading
+button.setEnv('sandbox');
+button.load();
+```
+### Error Handling Best Practices
+```javascript
+button.onError(function(data) {
+    console.error('Full error object:', data);
+    // Check different error properties
+    const errorMessage = data.error?.message ||
+                         data.message ||
+                         'Unknown error occurred';
+    // Handle different error types
+    if (data.context?.operation === 'wallet_operation') {
+        // Handle wallet-specific errors
+        showWalletError(errorMessage);
+    } else {
+        // Handle general errors
+        showGeneralError(errorMessage);
+    }
+});
+```
+## 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. |
 # Click To Pay
 ## Overview