@paydock/client-sdk 1.139.0 → 1.140.1

package/docs/open-wallet-buttons-examples.md

@@ -2,11 +2,16 @@
 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.
-Currently supports Apple Pay and Google Pay, with more wallet types planned for future releases.
+
+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.
 
-## Open Wallet Buttons simple example
+## Apple Pay Open Wallet Button
 
 ### Container
 
@@ -14,103 +19,58 @@ If available in your client environment, you will display a simple button that u
 <div id="widget"></div>
 ```
 
-You must create a container for the Open Wallet Buttons. Inside this tag, the button will be initialized.
+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 wallet service through the PayDock dashboard and obtain the service ID that will be used to load the button configuration.
+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
 
-For Apple Pay and Google Pay wallets, the amount and currency are required:
-
-**Apple Pay Example:**
-```javascript
-let button = new paydock.OpenWalletButtons(
-    "#widget",
-    publicKeyOrAccessToken,
-    serviceId,
-    {
-        amount: 100,
-        currency: "USD",
-    },
-    [] // Optional: required meta fields validation
-);
-button.load();
-```
-
-**Google Pay Example:**
 ```javascript
-let button = new paydock.OpenWalletButtons(
+let button = new paydock.ApplePayOpenWalletButton(
     "#widget",
     publicKeyOrAccessToken,
     serviceId,
     {
         amount: 100,
-        currency: "USD",
-        merchant_name: "Your Store"
-    },
-    [] // Optional: required meta fields validation
+        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 { OpenWalletButtons } from '@paydock/client-sdk';
+import { ApplePayOpenWalletButton } from '@paydock/client-sdk';
 
-var button = new OpenWalletButtons(
+var button = new ApplePayOpenWalletButton(
     '#widget',
     publicKeyOrAccessToken,
     serviceId,
     {
         amount: 100,
-        currency: 'USD',
-    },
-    [] // Optional: required meta fields validation
-);
-button.load();
-```
-
-For Apple Pay with shipping enabled:
-```javascript
-let button = new paydock.OpenWalletButtons(
-    "#widget",
-    publicKeyOrAccessToken,
-    serviceId,
-    {
-        amount: 100,
-        currency: "USD",
-        amount_label: "Total",
-        country: "US",
-        request_shipping: true,
-        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
-            }
-        ]
-    },
-    ['amount_label', 'country', 'request_shipping'] // Required meta fields validation
+        currency: 'AUD',
+        country: 'AU',
+        amount_label: 'TOTAL',
+        store_name: 'My Store',
+    }
 );
 button.load();
 ```
 
 ### Constructor Parameters
 
-The OpenWalletButtons constructor accepts the following 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 service ID configured in PayDock dashboard
-4. **meta** (OpenWalletMeta): Configuration object with payment and wallet settings
-5. **requiredMetaFields** (string[], optional): Array of meta field names that must be present
+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
 
@@ -121,202 +81,7 @@ Bear in mind that you must set an environment before calling `button.load()`.
 button.setEnv('sandbox');
 ```
 
-### Full example
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <title>Title</title>
-</head>
-<body>
-    <h2>Payment using PayDock 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.OpenWalletButtons(
-            "#widget",
-            publicKeyOrAccessToken,
-            serviceId,
-            {
-                amount: 100,
-                currency: "USD",
-                amount_label: "Total",
-                country: "US",
-            },
-            ['amount', 'currency'] // Required meta fields
-        );
-        button.load();
-</script>
-</html>
-```
-
-## Open Wallet Buttons advanced example
-
-### 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 open wallet buttons available", data));
-```
-
-### 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.
-
-### Performing actions when shipping address is updated
-
-When shipping is enabled and the customer updates their shipping address, you can recalculate shipping costs and update the payment amount. **This handler is required when shipping is enabled** - if no handler is provided, an error will be thrown.
-
-```javascript
-button.onShippingAddressChange(async (data) => {
-    console.log("Shipping address updated:", data);
-    console.log("Address details:", {
-        country: data.address_country,
-        state: data.address_state,
-        city: data.address_city,
-        postcode: data.address_postcode,
-        contact: data.contact
-    });
-    
-    // Call your backend to recalculate shipping
-    const response = await fetch('/api/calculate-shipping', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            address_country: data.address_country,
-            address_state: data.address_state,
-            address_city: data.address_city,
-            address_postcode: data.address_postcode
-        })
-    });
-    
-    const result = await response.json();
-    
-    return {
-        amount: result.newAmount,
-        shipping_options: result.availableShippingOptions
-    };
-});
-```
-
-**Important**: This event handler is required when using shipping functionality.
-
-### Performing actions when shipping option is selected
-
-When the customer selects a different shipping option, you can update the total amount accordingly. **This handler is required when shipping options are provided** - if no handler is provided, an error will be thrown.
-
-```javascript
-button.onShippingOptionsChange(async (data) => {
-    console.log("Shipping option selected:", data);
-    console.log("Selected option:", {
-        id: data.shipping_option_id,
-        label: data.label,
-        detail: data.detail,
-        amount: data.amount
-    });
-    
-    // Call your backend to update total with new shipping cost
-    const response = await fetch('/api/update-shipping-cost', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            shipping_option_id: data.shipping_option_id,
-            shipping_amount: data.amount
-        })
-    });
-    
-    const result = await response.json();
-    
-    // Note: In some implementations, you might need to access data.data.amount
-    // Check your actual data structure in console.log output
-    return {
-        amount: result.newTotalAmount
-    };
-});
-```
-
-**Important**: This event handler is required when providing shipping options.
-
-### Handling errors
-
-Register a callback function to handle errors that occur during wallet operations.
-
-```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';
-});
-```
-
-### Apple Pay Full example
+### Full Apple Pay example
 
 ```html
 <!DOCTYPE html>
@@ -326,20 +91,21 @@ button.onCancel((data) => {
     <title>Apple Pay with Open Wallets</title>
 </head>
 <body>
-    <h2>Payment using PayDock Open Wallet Button!</h2>
+    <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.OpenWalletButtons(
+    let button = new paydock.ApplePayOpenWalletButton(
         "#widget",
         publicKeyOrAccessToken,
         serviceId,
         {
             amount: 100,
-            currency: "USD",
-            amount_label: "Total",
-            country: "US",
+            currency: "AUD",
+            country: "AU",
+            amount_label: "TOTAL",
+            store_name: "My Store",
             request_shipping: true,
             request_payer_name: true,
             request_payer_email: true,
@@ -392,57 +158,49 @@ button.onCancel((data) => {
                 }
             ],
             apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable']
-        },
-        ['amount_label', 'country', 'request_shipping', 'shipping_options', 'apple_pay_capabilities'] // Required fields validation
+        }
     );
-    
+
     button.setEnv('sandbox');
-    
-    button.onUnavailable((data) => {
+
+    button.onUnavailable(({ data }) => {
         console.log("Apple Pay not available:", data);
-        // Show alternative payment methods
     });
-    
-    button.onClick((data) => {
+
+    button.onClick(() => {
         console.log("Apple Pay button clicked");
-        // Perform pre-payment validation
     });
-    
-    button.onSuccess((data) => {
+
+    button.onSuccess(({ data }) => {
         console.log("Payment successful:", data);
-        // Process the OTT token on your backend
         processPayment(data.token);
     });
-    
-    button.onError((data) => {
+
+    button.onError(({ data }) => {
         console.error("Payment error:", data);
-        // Handle error appropriately
     });
-    
-    button.onCancel((data) => {
+
+    button.onCancel(() => {
         console.log("Payment cancelled");
-        // Handle cancellation
     });
-    
-    button.onShippingAddressChange(async (addressData) => {
-        // Update shipping costs based on address
-        const response = await updateShippingCosts(addressData);
+
+    button.onShippingAddressChange(async ({ data }) => {
+        const response = await updateShippingCosts(data);
         return {
             amount: response.newAmount,
             shipping_options: response.shippingOptions
         };
     });
-    
-    button.onShippingOptionsChange(async (optionData) => {
-        // Update total based on selected shipping option
-        const response = await updateTotal(optionData);
+
+    button.onShippingOptionsChange(async ({ data }) => {
+        const response = await updateTotal(data);
         return {
             amount: response.newAmount
         };
     });
-    
+
     button.load();
-    
+
     async function updateShippingCosts(addressData) {
         // Your shipping calculation logic based on address
         const baseAmount = 100;
@@ -460,25 +218,22 @@ button.onCancel((data) => {
                 amount: 18.00
             }
         ];
-        
+
         return {
             newAmount: baseAmount + updatedShippingOptions[0].amount,
             shippingOptions: updatedShippingOptions
         };
     }
-    
-    async function updateTotal(optionData) {
-        // Your total calculation logic
+
+    async function updateTotal(shippingOption) {
         const baseAmount = 100;
-        // Note: Check if you need data.data.amount or data.amount based on your implementation
-        const shippingAmount = optionData.amount || optionData.data?.amount;
+        const shippingAmount = shippingOption.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' },
@@ -489,7 +244,262 @@ button.onCancel((data) => {
 </html>
 ```
 
-### Google Pay Full Example
+### 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, registering `onShippingAddressChange` and `onShippingOptionsChange` handlers lets you recalculate totals and update shipping options dynamically. If no handler is registered (or the handler throws), the SDK auto-accepts with the current amount and options.
+
+```javascript
+button.onShippingAddressChange(async function({ data }) {
+    console.log("Shipping address has been updated", data);
+    return {
+        amount: newAmount,
+        shipping_options: updatedShippingOptions
+    };
+});
+
+button.onShippingOptionsChange(async function({ data }) {
+    console.log("Shipping option selected", data);
+    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>
@@ -504,30 +514,23 @@ button.onCancel((data) => {
 </body>
 <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
 <script>
-    let button = new paydock.OpenWalletButtons(
+    let button = new paydock.GooglePayOpenWalletButton(
         "#widget",
         publicKeyOrAccessToken,
         serviceId,
         {
             amount: 100,
-            currency: "USD",
-            amount_label: "Total",
+            currency: "AUD",
             country: "AU",
+            amount_label: "Total",
             request_shipping: true,
             show_billing_address: true,
             merchant_name: 'Test Merchant',
             style: {
-                google: {
-                    button_type: 'buy',
-                    button_color: 'default',
-                    button_size_mode: 'fill'
-                }
+                button_type: 'buy',
+                button_color: 'default',
+                button_size_mode: 'fill'
             },
-            // Google Pay specific properties
-            payment_method_type: 'CARD',
-            allowed_auth_methods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
-            allowed_card_networks: ['AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA'],
-            billing_address_required: true,
             shipping_options: [
                 {
                     id: "standard",
@@ -539,64 +542,56 @@ button.onCancel((data) => {
                 {
                     id: "express",
                     label: "Express Shipping",
-                    detail: "Arrives in 1 to 2 days", 
+                    detail: "Arrives in 1 to 2 days",
                     amount: 15.00,
                     type: "PICKUP"
                 }
             ]
-        },
-        ['amount_label', 'country', 'request_shipping', 'shipping_options', 'merchant_name']
+        }
     );
-    
+
     button.setEnv('sandbox');
-    
-    // Required handlers
-    button.onSuccess((data) => {
+
+    button.onSuccess(({ data }) => {
         console.log("Payment successful:", data);
         processPayment(data.token);
     });
-    
-    button.onShippingAddressChange(async (addressData) => {
-        const response = await updateShippingCosts(addressData);
+
+    button.onShippingAddressChange(async ({ data }) => {
+        const response = await updateShippingCosts(data);
         return {
             amount: response.newAmount,
             shipping_options: response.shippingOptions
         };
     });
-    
-    button.onShippingOptionsChange(async (optionData) => {
-        const response = await updateTotal(optionData);
+
+    button.onShippingOptionsChange(async ({ data }) => {
+        const response = await updateTotal(data);
         return {
             amount: response.newAmount
         };
     });
-    
-    // Optional handlers
-    button.onUnavailable((data) => {
+
+    button.onUnavailable(({ data }) => {
         console.log("Google Pay not available:", data);
-        // Show alternative payment methods
     });
-    
-    button.onError((data) => {
+
+    button.onError(({ data }) => {
         console.error("Payment error:", data);
-        // Handle error appropriately
     });
-    
-    button.onCancel((data) => {
+
+    button.onCancel(() => {
         console.log("Payment cancelled");
-        // Handle cancellation
     });
-    
-    button.onClick((data) => {
+
+    button.onClick(() => {
         console.log("Google Pay button clicked");
-        // Perform pre-payment validation
     });
-    
+
     button.load();
-    
-    // Helper functions (same implementation as Apple Pay example)
+
+    // Helper functions
     async function updateShippingCosts(addressData) {
-        // Your shipping calculation logic based on address
         const baseAmount = 100;
         const updatedShippingOptions = [
             {
@@ -614,24 +609,22 @@ button.onCancel((data) => {
                 type: "PICKUP"
             }
         ];
-        
+
         return {
             newAmount: baseAmount + updatedShippingOptions[0].amount,
             shippingOptions: updatedShippingOptions
         };
     }
-    
-    async function updateTotal(optionData) {
-        // Your total calculation logic
+
+    async function updateTotal(shippingOption) {
         const baseAmount = 100;
-        const shippingAmount = optionData.amount || optionData.data?.amount;
+        const shippingAmount = shippingOption.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' },
@@ -642,264 +635,207 @@ button.onCancel((data) => {
 </html>
 ```
 
-### 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 OpenWalletButtons class.
+## Common API
 
-**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)
-- `onShippingAddressChange(handler)` - **Required for shipping** - Address change events
-- `onShippingOptionsChange(handler)` - **Required for shipping options** - Option change events
-
-**Event Handler Patterns:**
+Both `ApplePayOpenWalletButton` and `GooglePayOpenWalletButton` share the same event handler API inherited from the base class.
 
-```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
+### Checking for button availability
 
-// 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()
+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.
 
-// Click handler with flow control
-button.onClick(handler);  // Use data.attachResult() for async operations
+```javascript
+button.onUnavailable(({ data }) => console.log("No wallet button available", data));
 ```
 
-### Configuration Options
+### Service type validation
 
-#### Required Meta Fields
+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`:
 
-- `amount`: The payment amount (number)
-- `currency`: The currency code (string, e.g., "USD")
+```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
+);
 
-#### PayDock-Specific Meta Fields
+button.onError(({ data }) => {
+    // Error: Service configuration type 'ApplePay' does not match expected wallet type 'google'.
+    console.error(data.error.message);
+});
 
-The following are PayDock-specific properties available in `OpenWalletMeta`:
+button.load();
+```
 
-**Payment Configuration:**
-- `amount_label?: string`: Label for the total amount
-- `country?: string`: Country code (e.g., "US")
-- `capture?: boolean`: Whether to capture the payment immediately
-- `reference?: string`: Payment reference
-- `id?: string`: Payment ID
-- `credentials?: object`: Gateway credentials
+### 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 its return value: return `false` to abort, return a `Promise` to defer the wallet sheet, or throw an error to abort.
 
-**Contact and Shipping:**
-- `request_shipping?: boolean`: Enable shipping address collection
-- `request_payer_name?: boolean`: Request payer name
-- `request_payer_email?: boolean`: Request payer email  
-- `request_payer_phone?: boolean`: Request payer phone
-- `show_billing_address?: boolean`: Show billing address fields
-- `shipping_options?: IShippingOption[]`: Array of shipping options
-
-**UI and Display:**
-- `style?: WalletStyles`: Button styling options
-- `pay_later?: boolean`: Enable pay later options
-- `hide_message?: boolean`: Hide payment messages
-- `standalone?: boolean`: Standalone mode
-- `merchant_name?: string`: Merchant display name
-
-**Wallet-Specific:**
-- `apple_pay_capabilities?: string[]`: Apple Pay capability requirements
-- `wallets?: WALLET_TYPES[]`: Supported wallet types
-- `access_token?: string`: Access token
-- `refresh_token?: string`: Refresh token
-- `client_id?: string`: Client ID
-
-#### Extended Native Properties
-Since `OpenWalletMeta` extends `ApplePayJS.ApplePayPaymentRequest` and Google Pay interfaces, you can use any native Apple Pay or Google Pay properties directly in the configuration object alongside PayDock properties. See the [Extended Interface Properties](#extended-interface-properties) section for comprehensive details.
-
-#### Configuration Comparison Quick Reference
-
-| Feature | PayDock Property | Apple Pay Native Property | Google Pay Native Property |
-|---------|------------------|---------------------------|----------------------------|
-| **Country** | `country: 'US'` | `countryCode: 'US'` | `parameters.allowedCountries: ['US']` |
-| **Currency** | `currency: 'USD'` | `currencyCode: 'USD'` | Via PayDock property |
-| **Amount** | `amount: 100` | `total: { amount: '100.00' }` | Via PayDock property |
-| **Billing Address** | `show_billing_address: true` | `requiredBillingContactFields: [...]` | `billingAddressRequired: true` |
-| **Shipping Address** | `request_shipping: true` | `requiredShippingContactFields: [...]` | `shippingAddressRequired: true` |
-| **Card Networks** | Auto-configured | `supportedNetworks: ['visa', ...]` | `allowedCardNetworks: ['VISA', ...]` |
-| **Button Style** | `style.apple.button_style` | Via PayDock style property | `style.google.button_color` |
-
-#### Apple Pay Specific Style Options
 ```javascript
-style: {
-    apple: {
-        button_type: 'add-money' | 'book' | 'buy' | 'check-out' | 'continue' | 'contribute' | 'donate' | 'order' | 'pay' | 'plain' | 'reload' | 'rent' | 'set-up' | 'subscribe' | 'support' | 'tip' | 'top-up',
-        button_style: 'black' | 'white' | 'white-outline'
-    },
-    google: {
-        button_type: 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe',
-        button_color: 'default' | 'black' | 'white',
-        button_size_mode: 'static' | 'fill'
+// Synchronous — continue normally
+button.onClick(() => {
+    console.log("Perform actions on button click");
+});
+
+// Synchronous — return false to abort the payment flow
+button.onClick(() => {
+    if (!isOrderValid()) return false;
+});
+
+// Asynchronous — defer the wallet sheet until the promise resolves
+button.onClick(async () => {
+    const response = await fetch('/api/validate-order');
+    const result = await response.json();
+    if (!result.valid) {
+        throw new Error('Order validation failed');
     }
-}
+});
 ```
 
-### Google Pay Specific Properties
+### Handling successful OTT creation
 
-The following are Google Pay-specific properties available in `GooglePayMeta`:
+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.
 
-**Payment Method Configuration:**
-- `payment_method_type?: google.payments.api.PaymentMethodType`: Payment method type (usually 'CARD')
-- `allowed_auth_methods?: google.payments.api.CardAuthMethod[]`: Authentication methods (e.g., ['PAN_ONLY', 'CRYPTOGRAM_3DS'])
-- `allowed_card_networks?: google.payments.api.CardNetwork[]`: Supported card networks (e.g., ['AMEX', 'DISCOVER', 'INTERAC', 'JCB', 'MASTERCARD', 'VISA'])
+```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);
 
-**Billing Address Configuration:**
-- `billing_address_required?: boolean`: Override for show_billing_address
-- `billing_address_format?: google.payments.api.BillingAddressFormat`: Billing address format specification
+    fetch('/api/process-payment', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ott_token: data.token })
+    });
+});
+```
 
-**Merchant Configuration:**
-- `merchant_name?: string`: Display name for the merchant
+**Important**: The `onSuccess` event handler is mandatory. Not providing one will result in an error.
 
-### Extended Interface Properties
+### Updating meta after initialization
 
-The `OpenWalletMeta` interface extends native Apple Pay and Google Pay interfaces, giving you access to their native properties alongside PayDock-specific configurations:
+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:
 
-- Extends `ApplePayJS.ApplePayPaymentRequest` (full Apple Pay interface)
-- Extends `google.payments.api.IsReadyToPayPaymentMethodSpecification` (except `tokenizationSpecification`)
-- Extends `google.payments.api.PaymentMethodSpecification`
+```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' });
+```
 
-#### Apple Pay Extended Properties (ApplePayJS.ApplePayPaymentRequest)
+### Handling errors
 
-Since `OpenWalletMeta` extends `ApplePayJS.ApplePayPaymentRequest`, you can use any native Apple Pay property:
+Register a callback function to handle errors that occur during wallet operations, including service type mismatches.
 
 ```javascript
-const applePayConfig = {
-    // PayDock specific properties
-    amount: 100,
-    currency: 'USD',
-    amount_label: 'Total',
-    country: 'US',
-    
-    // Native Apple Pay properties
-    countryCode: 'US',           // Country code for the payment
-    currencyCode: 'USD',         // Currency code for the payment
-    merchantCapabilities: [       // Merchant capabilities
-        'supports3DS',
-        'supportsCredit', 
-        'supportsDebit'
-    ],
-    supportedNetworks: [         // Supported card networks
-        'visa',
-        'masterCard',
-        'amex',
-        'discover'
-    ],
-    requiredBillingContactFields: [  // Required billing fields
-        'name',
-        'postalAddress',
-        'email',
-        'phone'
-    ],
-    requiredShippingContactFields: [ // Required shipping fields
-        'postalAddress',
-        'name',
-        'phone',
-        'email'
-    ],
-    supportedCountries: [        // Supported countries for shipping
-        'US', 'CA', 'GB'
-    ],
-    total: {                     // Total amount object
-        label: 'Total',
-        amount: '100.00',
-        type: 'final'
-    },
-    shippingContact: {           // Pre-filled shipping contact
-        givenName: 'John',
-        familyName: 'Doe',
-        emailAddress: 'john@example.com'
-    },
-    billingContact: {            // Pre-filled billing contact
-        givenName: 'John',
-        familyName: 'Doe'
-    }
-};
+button.onError(({ data }) => {
+    console.error("Open Wallet error:", data.error);
+    console.log("Error context:", data.context);
+
+    showErrorMessage("Payment initialization failed. Please try again.");
+});
 ```
 
-#### Google Pay Extended Properties 
+### Handling checkout cancellation
 
-Since `OpenWalletMeta` extends Google Pay interfaces, you can use native Google Pay properties:
+When the user cancels or closes the wallet payment interface, you can perform cleanup operations.
 
 ```javascript
-const googlePayConfig = {
-    // PayDock specific properties
-    amount: 100,
-    currency: 'USD',
-    amount_label: 'Total',
-    country: 'US',
-    
-    // Native Google Pay properties (from IsReadyToPayPaymentMethodSpecification)
-    type: 'CARD',                // Payment method type
-    parameters: {
-        allowedAuthMethods: [    // Allowed authentication methods
-            'PAN_ONLY',
-            'CRYPTOGRAM_3DS'
-        ],
-        allowedCardNetworks: [   // Allowed card networks
-            'AMEX',
-            'DISCOVER', 
-            'JCB',
-            'MASTERCARD',
-            'VISA'
-        ],
-        billingAddressRequired: true,     // Require billing address
-        billingAddressParameters: {       // Billing address parameters
-            format: 'FULL',
-            phoneNumberRequired: true
-        }
-    },
-    
-    // Note: tokenizationSpecification is omitted from OpenWalletMeta
-    // as it's handled automatically by PayDock
-};
+button.onCancel(() => {
+    console.log("Wallet checkout cancelled");
+    window.location.href = '/checkout';
+});
 ```
 
-#### Property Inheritance
+### Cleaning up
+
+Remove the wallet button from the DOM when it is no longer needed:
+
+```javascript
+button.destroy();
+```
 
-Since `OpenWalletMeta` extends native Apple Pay and Google Pay interfaces, you get access to both:
+### 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.
 
-1. **PayDock Properties**: Simplified, cross-wallet properties (e.g., `amount`, `currency`, `country`)
-2. **Native Extended Properties**: Full native wallet properties (e.g., `merchantCapabilities`, `supportedNetworks`)
+**Available Event Handler Methods:**
+- `onClick(handler)` - Button click events (return `false` to abort, `Promise` to defer)
+- `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)` - **Recommended for shipping** - Address change events (auto-accepted if not registered)
+- `onShippingOptionsChange(handler)` - **Recommended for shipping options** - Option change events (auto-accepted if not registered)
 
-Both types of properties can be used together in the same configuration object:
+**Event Handler Patterns:**
 
 ```javascript
-// Example combining PayDock and native properties
-const config = {
-    // PayDock simplified properties
-    amount: 100,
-    currency: 'USD',
-    country: 'US',
-    show_billing_address: true,
-    
-    // Native Apple Pay properties (available due to interface extension)
-    merchantCapabilities: ['supports3DS', 'supportsCredit'],
-    supportedNetworks: ['visa', 'masterCard', 'amex'],
-    requiredBillingContactFields: ['name', 'postalAddress'],
-    
-    // Native Google Pay properties (available due to interface extension)
-    type: 'CARD',
-    parameters: {
-        allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
-        allowedCardNetworks: ['VISA', 'MASTERCARD', 'AMEX']
-    }
-};
+// Required handler
+button.onSuccess(handler);  // Always required
+
+// Recommended when shipping is enabled (auto-accepted if not registered)
+button.onShippingAddressChange(handler);
+button.onShippingOptionsChange(handler);
+
+// 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);  // Return false to abort, or a Promise to defer
+
+// Loaded handler
+button.onLoaded(handler);  // Notified when button renders
 ```
 
-**Important Notes**:
-- PayDock automatically handles the conversion and mapping between your configuration and the appropriate wallet APIs
-- The `tokenizationSpecification` property is omitted from the Google Pay interface extension as PayDock handles tokenization automatically  
-- All properties shown are directly available in the `OpenWalletMeta` configuration object
+### 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
+### Shipping Options Format
 ```javascript
 shipping_options: [
     {
@@ -907,12 +843,12 @@ shipping_options: [
         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
+        date_components_range: {   // Optional: delivery date range (Apple Pay only)
             start_date_components: {
-                years: 0,          // Years from now
-                months: 0,         // Months from now  
-                days: 5,           // Days from now
-                hours: 0,          // Hours from now
+                years: 0,
+                months: 0,
+                days: 5,
+                hours: 0,
             },
             end_date_components: {
                 years: 0,
@@ -925,263 +861,28 @@ shipping_options: [
 ]
 ```
 
-**Important**: 
+**Important**:
 - `amount` should be a **number**, not a string
-- `date_components_range` is optional but provides delivery estimates
+- `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`
 
-#### Required Meta Fields Validation
-
-The `requiredMetaFields` parameter allows you to specify which fields in the meta object must be present. If any required field is missing, the constructor will throw an error:
-
-```javascript
-// Example with validation
-const button = new paydock.OpenWalletButtons(
-    '#widget',
-    publicKeyOrAccessToken,
-    serviceId,
-    {
-        amount: 100,
-        currency: 'USD',
-        // Missing amount_label will cause an error
-    },
-    ['amount', 'currency', 'amount_label'] // This will throw an error
-);
-
-// To avoid validation, pass an empty array or omit the parameter
-const button = new paydock.OpenWalletButtons(
-    '#widget',
-    publicKeyOrAccessToken,
-    serviceId,
-    meta,
-    [] // No validation
-);
-```
-
-### Complete Test Setup Example
-
-Based on the actual test implementation, here's a complete working example for testing:
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Open Wallet Apple Pay Test</title>
-</head>
-<body>
-    <h1>Apple Pay Test Page</h1>
-    <table>
-        <tr>
-            <td>Service ID:</td>
-            <td><input type="text" id="service_id" placeholder="Enter your service ID" /></td>
-        </tr>
-        <tr>
-            <td>Access Token/Public Key:</td>
-            <td><input type="text" id="access_token" placeholder="Enter your access token" /></td>
-        </tr>
-    </table>
-    <button onclick="loadApplePayButton()">Load Apple Pay Button</button>
-    <div id="widget"></div>
-
-    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js"></script>
-    <script>
-        function loadApplePayButton() {
-            const shippingOptions = [
-                {
-                    label: "Standard Shipping",
-                    detail: "Arrives in 5-7 business days",
-                    amount: 10,
-                    id: "standard",
-                    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 }
-                    }
-                },
-                {
-                    label: "Express Shipping",
-                    detail: "Arrives in 1-2 business days",
-                    amount: 20,
-                    id: "express",
-                    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 }
-                    }
-                }
-            ];
-
-            const widget = new paydock.OpenWalletButtons(
-                '#widget',
-                document.getElementById("access_token").value,
-                document.getElementById("service_id").value,
-                {
-                    amount: 100,
-                    currency: 'USD',
-                    country: 'US',
-                    amount_label: 'Total',
-            apple_pay_capabilities: [
-                'credentials_available', 
-                'credentials_status_unknown', 
-                'credentials_unavailable'
-            ],
-            shipping_options: shippingOptions,
-            request_shipping: true,
-            
-            // Extended Apple Pay properties (native interface)
-            merchantCapabilities: [
-                'supports3DS',
-                'supportsCredit', 
-                'supportsDebit'
-            ],
-            supportedNetworks: [
-                'visa',
-                'masterCard',
-                'amex',
-                'discover'
-            ],
-            requiredBillingContactFields: [
-                'name',
-                'postalAddress'
-            ],
-            requiredShippingContactFields: [
-                'postalAddress',
-                'name', 
-                'phone',
-                'email'
-            ]
-                },
-                ['amount_label', 'country', 'request_shipping', 'shipping_options', 'apple_pay_capabilities']
-            );
-
-            // Required handlers
-            widget.onSuccess(async function (data) {
-                console.log("Payment successful:", data);
-                // Process the OTT token
-                alert(`Payment successful! OTT Token: ${data.token}`);
-            });
-
-            widget.onShippingAddressChange(async function (data) {
-                console.log("Shipping address changed:", data);
-                
-                // Simulate updated shipping options based on address
-                const updatedOptions = [
-                    { label: "Local Delivery", detail: "Same day delivery", amount: 5, id: "local" },
-                    { label: "Regional Delivery", detail: "Next day delivery", amount: 15, id: "regional" }
-                ];
-
-                return {
-                    amount: 100 + updatedOptions[0].amount,
-                    shipping_options: updatedOptions
-                };
-            });
-
-            widget.onShippingOptionsChange(async function (data) {
-                console.log("Shipping option changed:", data);
-                
-                // Note: Check your actual data structure - might be data.data.amount
-                const shippingCost = data.amount || data.data?.amount || 0;
-                return {
-                    amount: 100 + shippingCost
-                };
-            });
-
-            // Optional handlers
-            widget.onError(function (data) {
-                console.error("Payment error:", data);
-                alert("Payment failed: " + data.error.message);
-            });
-
-            widget.onCancel(function (data) {
-                console.log("Payment cancelled:", data);
-                alert("Payment was cancelled");
-            });
-
-            widget.onClick(function (data) {
-                console.log("Apple Pay button clicked:", data);
-                // Optional: Add validation logic here
-            });
-
-            widget.setEnv('sandbox');
-            widget.load();
-        }
-    </script>
-</body>
-</html>
-```
-
-### Common Issues and Troubleshooting
-
-#### Event Data Structure Variations
-Different implementations might return data in slightly different structures. Always check the actual data structure in your console:
-
-```javascript
-// In your event handlers, log the data to see the actual structure
-widget.onShippingOptionsChange(async function (data) {
-    console.log("Full data object:", data);
-    
-    // Try different access patterns based on your implementation
-    const amount = data.amount ||           // Direct access
-                  data.data?.amount ||      // Nested in data property
-                  data.shippingCost ||      // Alternative property name
-                  0;                        // Fallback
-    
-    return { amount: baseAmount + amount };
-});
-```
-
-#### Required vs Optional Configuration
-```javascript
-// Minimal required configuration
-const minimalConfig = {
-    amount: 100,
-    currency: 'USD'
-};
-
-// Recommended configuration with validation
-const recommendedConfig = {
-    amount: 100,
-    currency: 'USD',
-    amount_label: 'Total',
-    country: 'US',
-    apple_pay_capabilities: ['credentials_available']
-};
-
-// Full configuration with shipping
-const fullConfig = {
-    amount: 100,
-    currency: 'USD',
-    amount_label: 'Total', 
-    country: 'US',
-    request_shipping: true,
-    shipping_options: [...],
-    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable']
-};
-```
-
-#### Environment Setup
+### Environment Setup
 ```javascript
 // Always set environment before loading
-widget.setEnv('sandbox');
-widget.load();
+button.setEnv('sandbox');
+button.load();
 ```
 
-#### Error Handling Best Practices
+### Error Handling Best Practices
 ```javascript
-widget.onError(function(data) {
+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
+
+    const errorMessage = data.error?.message || 'Unknown error occurred';
+
     if (data.context?.operation === 'wallet_operation') {
-        // Handle wallet-specific errors
         showWalletError(errorMessage);
     } else {
-        // Handle general errors
         showGeneralError(errorMessage);
     }
 });