npm - @paydock/client-sdk - Versions diffs - 1.131.0 → 1.133.1-beta - Mend

@paydock/client-sdk 1.131.0 → 1.133.1-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 (135) hide show

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

@@ -0,0 +1,1188 @@
+## 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.
+Currently supports Apple Pay and Google Pay, with more wallet types planned for future releases.
+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
+### Container
+```html
+<div id="widget"></div>
+```
+You must create a container for the Open Wallet Buttons. 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.
+### 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(
+    "#widget",
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: "USD",
+        merchant_name: "Your Store"
+    },
+    [] // Optional: required meta fields validation
+);
+button.load();
+```
+```javascript
+// ES2015 | TypeScript
+import { OpenWalletButtons } from '@paydock/client-sdk';
+var button = new OpenWalletButtons(
+    '#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
+);
+button.load();
+```
+### Constructor Parameters
+The OpenWalletButtons 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
+### 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 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
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Apple Pay with Open Wallets</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",
+            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']
+        },
+        ['amount_label', 'country', 'request_shipping', 'shipping_options', 'apple_pay_capabilities'] // Required fields validation
+    );
+    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;
+        // Note: Check if you need data.data.amount or data.amount based on your implementation
+        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>
+```
+### Google Pay Full 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.OpenWalletButtons(
+        "#widget",
+        publicKeyOrAccessToken,
+        serviceId,
+        {
+            amount: 100,
+            currency: "USD",
+            amount_label: "Total",
+            country: "AU",
+            request_shipping: true,
+            show_billing_address: true,
+            merchant_name: 'Test Merchant',
+            style: {
+                google: {
+                    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",
+                    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"
+                }
+            ]
+        },
+        ['amount_label', 'country', 'request_shipping', 'shipping_options', 'merchant_name']
+    );
+    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 (same implementation as Apple Pay example)
+    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,
+                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) {
+        // 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>
+```
+### 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.
+**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:**
+```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
+```
+### Configuration Options
+#### Required Meta Fields
+- `amount`: The payment amount (number)
+- `currency`: The currency code (string, e.g., "USD")
+#### PayDock-Specific Meta Fields
+The following are PayDock-specific properties available in `OpenWalletMeta`:
+**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
+**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'
+    }
+}
+```
+### Google Pay Specific Properties
+The following are Google Pay-specific properties available in `GooglePayMeta`:
+**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'])
+**Billing Address Configuration:**
+- `billing_address_required?: boolean`: Override for show_billing_address
+- `billing_address_format?: google.payments.api.BillingAddressFormat`: Billing address format specification
+**Merchant Configuration:**
+- `merchant_name?: string`: Display name for the merchant
+### Extended Interface Properties
+The `OpenWalletMeta` interface extends native Apple Pay and Google Pay interfaces, giving you access to their native properties alongside PayDock-specific configurations:
+- Extends `ApplePayJS.ApplePayPaymentRequest` (full Apple Pay interface)
+- Extends `google.payments.api.IsReadyToPayPaymentMethodSpecification` (except `tokenizationSpecification`)
+- Extends `google.payments.api.PaymentMethodSpecification`
+#### Apple Pay Extended Properties (ApplePayJS.ApplePayPaymentRequest)
+Since `OpenWalletMeta` extends `ApplePayJS.ApplePayPaymentRequest`, you can use any native Apple Pay property:
+```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'
+    }
+};
+```
+#### Google Pay Extended Properties
+Since `OpenWalletMeta` extends Google Pay interfaces, you can use native Google Pay properties:
+```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
+};
+```
+#### Property Inheritance
+Since `OpenWalletMeta` extends native Apple Pay and Google Pay interfaces, you get access to both:
+1. **PayDock Properties**: Simplified, cross-wallet properties (e.g., `amount`, `currency`, `country`)
+2. **Native Extended Properties**: Full native wallet properties (e.g., `merchantCapabilities`, `supportedNetworks`)
+Both types of properties can be used together in the same configuration object:
+```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']
+    }
+};
+```
+**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
+#### 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
+            start_date_components: {
+                years: 0,          // Years from now
+                months: 0,         // Months from now
+                days: 5,           // Days from now
+                hours: 0,          // Hours from now
+            },
+            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
+- 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
+```javascript
+// Always set environment before loading
+widget.setEnv('sandbox');
+widget.load();
+```
+#### Error Handling Best Practices
+```javascript
+widget.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);
+    }
+});
+```