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

@paydock/client-sdk 1.139.0 → 1.140.0-beta

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

Files changed (73) hide show

package/slate.md CHANGED Viewed

@@ -1311,6 +1311,1679 @@ Similarly, for **GooglePay via MPGS** you can initialize the `PaymentMethodSpeci
 </html>
 ```
+## Express Wallet Buttons
+Express Wallet Buttons allow to integrate with E-Wallets in an "express" operational mode, allowing to show the respective button in product or cart pages.
+The general flow to use the widgets is:
+1. Configure your gateway and connect it using Paydock API or Dashboard.
+2. Create a container in your site
+```html
+<div id="widget"></div>
+```
+3. Initialize the specific WalletButtonExpress, providing your Access Token (preferred) or Public Key, plus required and optional meta parameters for the wallet in use. The general format is:
+```js
+new paydock.{Provider}WalletButtonExpress(
+    "#widget",
+    accessTokenOrPublicKey,
+    gatewayId,
+    gatewaySpecificMeta,
+);
+```
+4. (optional) If the screen where the button is rendered allows for cart/amount changes, call `setMeta` method to update the meta information.
+5. Handle the `onClick` callback, where you should call your server, initialize the wallet charge via `POST v1/charges/wallet` and return the wallet token.
+6. Handle the `onPaymentSuccessful`, `onPaymentError` and `onPaymentInReview` (if fraud is applicable) for payment results.
+### Supported Providers
+1. [Apple Pay](#apple-pay-wallet-button-express)
+2. [Paypal](#paypal-wallet-button-express)
+### Apple Pay Wallet Button Express
+A full description of the meta parameters for [ApplePayWalletButtonExpress](#ApplePayWalletButtonExpress) meta parameters can be found [here](#ApplePayWalletMeta). Below you will find a fully working html example.
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+    <h2>Payment using PayDock ApplePayWalletButtonExpress!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.ApplePayWalletButtonExpress(
+        "#widget",
+        accessTokenOrPublicKey,
+        gatewayId,
+        {
+            amount_label: 'TOTAL',
+            country: 'AU',
+            currency: 'AUD',
+            amount: 15.5,
+            // merchant_capabilities: ['supports3DS', 'supportsEMV', 'supportsCredit', 'supportsDebit'],
+            // supported_networks: ['visa', 'masterCard', 'amex', 'chinaUnionPay', 'discover', 'interac', 'jcb', 'privateLabel'],
+            // required_billing_contact_fields: ['email', 'name', 'phone', 'postalAddress'], // phone and email do not work according to relevant testing
+            // required_shipping_contact_fields: ['email', 'phone'], // Workaround to pull phone and email from shipping contact instead - does not require additional shipping address information
+            // supported_countries: ["AU"],
+            // style: {
+            //     button_type: "buy",
+            //     button_style: "black",
+            // },
+        }
+    );
+    button.setEnv('sandbox');
+    button.onUnavailable(function() {
+        console.log("Button not available");
+    });
+    button.onError(function(error) {
+        console.log("On Error Callback", error);
+    });
+    button.onPaymentSuccessful(function(data) {
+        console.log("Payment successful");
+        console.log(data);
+    });
+    button.onPaymentError(function(err) {
+        console.log("Payment error");
+        console.log(err);
+    });
+    button.onPaymentInReview(function(data) {
+        console.log("The payment is on fraud review");
+        console.log(data);
+    });
+    button.onClick(async (data) => {
+        console.log("Button clicked", data);
+        const responseData = await fetch('https://your-server-url/initialize-wallet-charge');
+        const parsedData = await responseData.json();
+        return parsedData.resource.data.token;
+    });
+    button.onCheckoutClose(() => {
+        console.log("Checkout closed");
+    });
+    button.load();
+</script>
+</html>
+```
+### Apple Pay Wallet Button Express with Shipping
+A full description of the meta parameters for [ApplePayWalletButtonExpress](#ApplePayWalletButtonExpress) meta parameters can be found [here](#ApplePayWalletMeta). Below you will find a fully working html example.
+```html
+<html>
+<head>
+    <title>Apple Pay Express test page</title>
+    <style>
+        #inputModal {
+            display: none;
+            position: fixed;
+            left: 0;
+            top: 0;
+            width: 100%;
+            height: 100%;
+            background-color: rgba(0,0,0,0.5);
+            z-index: 1000;
+        }
+        #inputBox {
+            position: absolute;
+            left: 50%;
+            top: 50%;
+            transform: translate(-50%, -50%);
+            padding: 20px;
+            background: white;
+            border-radius: 5px;
+            box-shadow: 2px 2px 10px rgba(0,0,0,0.5);
+        }
+    </style>
+</head>
+<body>
+    <table id='paymentTable'>
+        <tr>
+            <td>Environment:</td>
+            <td>
+                <select id="environment" name="environment">
+                    <option value="sandbox">Sandbox</option>
+                    <option value="local">Local</option>
+                </select>
+            </td>
+        </tr>
+        <tr>
+            <td>Access Token / Public Key:</td>
+            <td><input type="text" name="access" id="access" /></td>
+        </tr>
+        <tr>
+            <td>Secret Key:</td>
+            <td><input type="text" name="secretKey" id="secretKey" /></td>
+        </tr>
+        <tr>
+            <td>Gateway Id:</td>
+            <td><input type="text" name="gateway" id="gateway" /></td>
+        </tr>
+        <tr>
+            <td>Wallet Charge - for apple pay we need to add it here because the apple pay popup does not allow us to
+                inject it there but it will be used only on click. So is optional, if not provided it simulates an error
+                when creating B2B wallet charge on click:</td>
+            <td><input type="text" name="token" id="token" /></td>
+        </tr>
+        <tr>
+            <td>Charge id - Used to update the charge with the shipping data/shipping options</td>
+            <td><input type="text" name="chargeId" id="chargeId" /></td>
+        </tr>
+        <tr>
+            <td>Meta:</td>
+            <td><textarea id="meta" name="meta" rows="4" cols="50"></textarea></td>
+        </tr>
+    </table>
+    <div id="button">
+        <input type="submit" name="event" value="Send" class="button" onclick="return loadButtons()" />
+    </div>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js"></script>
+<script type=text/javascript>
+    // Environment enum with API URLs
+    const ENVIRONMENTS = {
+        PRODUCTION: {
+            name: 'production',
+            apiUrl: 'https://api.paydock.com'
+        },
+        SANDBOX: {
+            name: 'sandbox',
+            apiUrl: 'https://api-sandox.paydock.com'
+        }
+    };
+    // Function to get API URL based on selected environment
+    function getApiUrl(environmentName) {
+        const env = Object.values(ENVIRONMENTS).find(env => env.name === environmentName);
+        return env ? env.apiUrl : ENVIRONMENTS.SANDBOX.apiUrl;
+    }
+    // Function to get current base URL from selected environment
+    function getBaseUrl() {
+        const selectedEnvironment = document.getElementById("environment").value;
+        return getApiUrl(selectedEnvironment);
+    }
+    async function updateCharge(secretKey, chargeId, updateData) {
+        try {
+            const baseUrl = getBaseUrl();
+            const response = await fetch(`${baseUrl}/v1/charges/wallet/${chargeId}`, {
+                method: 'PUT',
+                headers: {
+                    'x-user-secret-key': secretKey,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(updateData),
+            });
+            const data = await response.json();
+            console.log('Update charge response:', data);
+            return data;
+        } catch (error) {
+            console.error('Error updating charge:', error);
+        }
+    };
+    const shippingOptions = [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+                date_components_range: {
+                    start_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 5,
+                        hours: 0,
+                    },
+                    end_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 10,
+                        hours: 0,
+                    }
+                }
+            },
+            {
+                label: "Test 2",
+                detail: "This is a test 2 shipping methods",
+                amount: 14,
+                id: "randomId2",
+                date_components_range: {
+                    start_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 6,
+                        hours: 0,
+                    },
+                    end_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 12,
+                        hours: 0,
+                    },
+                },
+            },
+        ];
+    function loadButtons() {
+        const secretKey = document.getElementById("secretKey").value;
+        if (!secretKey) {
+            alert("Please enter the secret key.");
+            return false;
+        }
+        let button = new paydock.ApplePayWalletButtonExpress(
+            "#widget",
+            document.getElementById("access").value,
+            document.getElementById("gateway").value,
+            JSON.parse(document.getElementById("meta").value),
+        );
+        button.setEnv(document.getElementById("environment").value);
+        let charge_id;
+        button.onClick(async (data) => {
+            const { token, chargeId } = await getUserInput();
+            charge_id = chargeId;
+            return token;
+        });
+        const amount = JSON.parse(document.getElementById('meta').value).amount;
+        button.onUnavailable(function() {
+            console.log("Button unavailable");
+        });
+        button.onError(function(error) {
+            console.log("On Error Callback", error);
+        });
+        button.onPaymentSuccessful(function(data) {
+            console.log("Payment successful");
+            console.log(data);
+        });
+        button.onPaymentError(function(err) {
+            console.log("Payment error");
+            console.log(err);
+        });
+        button.onPaymentInReview(function(data) {
+            console.log("The payment is on fraud review");
+            console.log(data);
+        });
+        button.onCheckoutClose(() => {
+            console.log("Checkout closed");
+        });
+        button.onShippingAddressChange(async function(data) {
+            console.log("Shipping address has been updated", data);
+            const defaultOption = shippingOptions[0];
+            const updateData = {
+                shipping: {
+                    ...data.data,
+                    amount: defaultOption.amount,
+                    method: defaultOption.id,
+                    options: shippingOptions,
+                },
+                amount: amount + defaultOption.amount
+            };
+            const res = await updateCharge(secretKey, charge_id, updateData);
+            return { token: res.resource.data.token };
+        });
+        button.onShippingOptionsChange(async function(data) {
+            console.log("Shipping options have been updated", JSON.stringify(data, null, 2));
+            const updateData = {
+                shipping: {
+                    method: data.data.shipping_option_id,
+                    amount: data.data.amount,
+                },
+                amount: amount + Number(data.data.amount)
+            };
+            const res = await updateCharge(secretKey, charge_id, updateData);
+            return { token: res.resource.data.token };
+        });
+        button.load()
+        document.getElementById("paymentTable").style.display = "none";
+        document.getElementById("button").style.display = "none";
+        return true;
+    }
+    function getUserInput(message) {
+        return new Promise((resolve, reject) => {
+            console.log("Simulating B2B call to generate token...");
+            setTimeout(() => {
+                const token = document.getElementById("token").value;
+                const chargeId = document.getElementById("chargeId").value;
+                if (token && chargeId)
+                    return resolve({ token, chargeId });
+                return reject("No token or Charge Id provided");
+            }, 2000);
+        });
+    }
+    document.addEventListener('DOMContentLoaded', () => {
+        // Function to get the value of a query parameter by name
+        function getQueryParam(name) {
+            const urlParams = new URLSearchParams(window.location.search);
+            return urlParams.get(name);
+        }
+        // Function to set input values from URL parameters
+        function setInputValues() {
+            const meta = {
+                apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+                amount_label: 'TOTAL',
+                country: 'AU',
+                currency: 'AUD',
+                amount: 10,
+                shipping_editing_mode: 'available', // available, 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: "qa.notifications+appleid@paydock.com",
+                        first_name: "QA",
+                        last_name: "QA",
+                    },
+                    options: shippingOptions,
+                },
+                // merchant_capabilities: ['supports3DS', 'supportsEMV', 'supportsCredit', 'supportsDebit'],
+                // supported_networks: ['visa', 'masterCard', 'amex', 'chinaUnionPay', 'discover', 'interac', 'jcb', 'privateLabel'],
+                // required_billing_contact_fields: ['email', 'name', 'phone', 'postalAddress', 'phoneticName'],
+                // required_shipping_contact_fields: ['email', 'phone' /*, 'name', 'postalAddress', 'phoneticName'*/],
+                // supported_countries: [],
+                // style: {
+                //     button_type: 'continue',
+                //     button_style: 'white',
+                // },
+            };
+            document.getElementById('meta').value = JSON.stringify(meta, null, 2);
+        }
+        setInputValues();
+    });
+</script>
+</html>
+```
+When supporting shipping, the method `onShippingAddressChange` and `onShippingOptionsChange` are required to update the shipping address and options.
+```javascript
+button.onShippingAddressChange(async function(data) {
+    console.log("Shipping address has been updated", data);
+    const updateData = {
+        shipping: {
+            ...data.data,
+            amount: defaultOption.amount,
+            method: defaultOption.id,
+            options: shippingOptions,
+        },
+        amount: amount + defaultOption.amount
+    };
+    const res = await updateCharge(secretKey, charge_id, updateData);
+    return { token: res.resource.data.token };
+});
+button.onShippingOptionsChange(async function(data) {
+    console.log("Shipping options have been updated", data);
+    const updateData = {
+        shipping: {
+            method: data.data.shipping_option_id,
+            amount: data.data.amount,
+        },
+        amount: amount + Number(data.data.amount)
+    };
+    const res = await updateCharge(secretKey, charge_id, updateData);
+    return { token: res.resource.data.token };
+});
+```
+The `updateCharge` method is a custom method to update the charge with the shipping data/shipping options. It is not part of the Paydock SDK and it should use the Paydock's public API to update the charge from the merchant's server.
+### Supported 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', // At least one of the fields is required so the shipping address is shown at Apple Pay.
+        '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: "qa.notifications+appleid@paydock.com",
+            first_name: "QA",
+            last_name: "QA",
+        },
+        options: [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+                date_components_range: {
+                    start_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 5,
+                        hours: 0,
+                    },
+                    end_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 10,
+                        hours: 0,
+                    }
+                }
+            }
+        ],
+    },
+}
+```
+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', // At least one of the fields is required so the shipping address is shown at Apple Pay.
+        '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: "qa.notifications+appleid@paydock.com",
+            first_name: "QA",
+            last_name: "QA",
+        },
+        options: [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+                date_components_range: {
+                    start_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 5,
+                        hours: 0,
+                    },
+                    end_date_components: {
+                        years: 0,
+                        months: 0,
+                        days: 10,
+                        hours: 0,
+                    }
+                }
+            }
+        ],
+    },
+}
+```
+#### Shipping address editable by the customer
+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', // At least one of the fields is required so the shipping address is shown at Apple Pay.
+        'name',
+        'phone',
+        'email',
+    ],
+}
+```
+When the the customer selects an address, the `onShippingAddressChange` method is called with the shipping address data. If the merchant wants to update the charge with the shipping address, it should update the charge using Paydock's public API Update Charge method with the shipping address data.
+It can include the shipping options in the update data, that will be used to show the shipping options in the Apple Pay popup.
+```javascript
+button.onShippingAddressChange(async function(data) {
+    console.log("Shipping address has been updated", data);
+    const updateData = {
+        shipping: {
+            ...data.data,
+            amount: defaultOption.amount,
+            method: defaultOption.id,
+            options: shippingOptions,
+        },
+        amount: amount + defaultOption.amount
+    };
+});
+```
+#### 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"]
+}
+```
+### Paypal Wallet Button Express
+A full description of the meta parameters for [PaypalWalletButtonExpress](#PaypalWalletButtonExpress) meta parameters can be found [here](#PaypalWalletMeta). Below you will find a fully working html example.
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+    <h2>Payment using PayDock PaypalWalletButtonExpress!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.PaypalWalletButtonExpress(
+        "#widget",
+        accessTokenOrPublicKey,
+        gatewayId,
+        {
+            amount: 15.5,
+            currency: 'AUD',
+            pay_later: false,
+            standalone: false,
+            capture: true,
+            // style: {
+            //     layout: 'horizontal', // or 'vertical'
+            //     color: 'gold', // or 'blue', 'silver', 'black', 'white'
+            //     shape: 'rect', // or 'pill', 'sharp'
+            //     borderRadius: 5,
+            //     height: 40,
+            //     disableMaxWidth: false,
+            //     label: 'paypal', // or 'checkout', 'buynow', 'pay', 'installment'
+            //     tagline: true,
+            //     messages: {
+            //         layout: 'text', // or 'flex'
+            //         logo: {
+            //             type: 'primary', // or 'alternative', 'inline', 'none'
+            //             position: 'left', // or 'right', 'top'
+            //         },
+            //         text: {
+            //             color: 'black', // or 'white', 'monochrome', 'grayscale'
+            //             size: 10, // or 11, 12, 13, 14, 15, 16
+            //             align: 'left', // or 'center', 'right'
+            //         },
+            //         color: 'blue', // or 'black', 'white', 'white-no-border', 'gray', 'monochrome', 'grayscale'
+            //         ratio: '1x1', // or '1x4', '8x1', '20x1'
+            //     },
+            // }
+        }
+    );
+    button.setEnv('sandbox');
+    button.onUnavailable(function() {
+        console.log("Button not available");
+    });
+    button.onError(function(error) {
+        console.log("On Error Callback", error);
+    });
+    button.onPaymentSuccessful(function(data) {
+        console.log("Payment successful");
+        console.log(data);
+    });
+    button.onPaymentError(function(err) {
+        console.log("Payment error");
+        console.log(err);
+    });
+    button.onPaymentInReview(function(data) {
+        console.log("The payment is on fraud review");
+        console.log(data);
+    });
+    button.onClick(async (data) => {
+        console.log("Button clicked", data);
+        const responseData = await fetch('https://your-server-url/initialize-wallet-charge');
+        const parsedData = await responseData.json();
+        return parsedData.resource.data.token;
+    });
+    button.onCheckoutClose(() => {
+        console.log("Checkout closed");
+    });
+    button.load();
+</script>
+</html>
+```
+## Open Wallet Buttons
+You can find description of all methods and parameters [here](https://www.npmjs.com/package/@paydock/client-sdk#open-wallet-buttons-simple-example)
+Open Wallet Buttons provide a next-generation approach to integrating E-Wallets into your checkout with improved event handling and more granular control over wallet interactions.
+Each wallet type has its own dedicated class with fully typed metadata:
+- [ApplePayOpenWalletButton](#ApplePayOpenWalletButton) - for Apple Pay integration
+- [GooglePayOpenWalletButton](#GooglePayOpenWalletButton) - for Google Pay integration
+On `load()`, each button fetches the service configuration from PayDock and validates that the service type matches the expected wallet. If there is a mismatch (e.g. using an Apple Pay service ID with `GooglePayOpenWalletButton`), an error will be raised via the `onError` callback.
+If available in your client environment, you will display a simple button that upon clicking it the user will follow the standard flow for the appropriate Wallet. If not available an event will be raised and no button will be displayed.
+## Apple Pay Open Wallet Button
+### Container
+```html
+<div id="widget"></div>
+```
+You must create a container for the Open Wallet Button. Inside this tag, the button will be initialized.
+Before initializing the button, you must configure your Apple Pay wallet service through the PayDock dashboard and obtain the service ID that will be used to load the button configuration.
+### Initialization
+```javascript
+let button = new paydock.ApplePayOpenWalletButton(
+    "#widget",
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: "AUD",
+        country: "AU",
+        amount_label: "TOTAL",
+        store_name: "My Store",
+        apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    }
+);
+button.load();
+```
+```javascript
+// ES2015 | TypeScript
+import { ApplePayOpenWalletButton } from '@paydock/client-sdk';
+var button = new ApplePayOpenWalletButton(
+    '#widget',
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: 'AUD',
+        country: 'AU',
+        amount_label: 'TOTAL',
+        store_name: 'My Store',
+    }
+);
+button.load();
+```
+### Constructor Parameters
+The ApplePayOpenWalletButton constructor accepts the following parameters:
+1. **selector** (string): CSS selector for the container element
+2. **publicKeyOrAccessToken** (string): Your PayDock public key or access token
+3. **serviceId** (string): The Apple Pay service ID configured in PayDock dashboard
+4. **meta** (ApplePayOpenWalletMeta): Apple Pay-specific configuration object
+> **Note:** Required meta fields (`amount`, `currency`, `country`, `amount_label`, `store_name`) are validated automatically by the `ApplePayOpenWalletButton` class. You do not need to specify them manually.
+### Setting environment
+Current method can change environment. By default environment = sandbox.
+Bear in mind that you must set an environment before calling `button.load()`.
+```javascript
+button.setEnv('sandbox');
+```
+### Full Apple Pay example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Apple Pay with Open Wallets</title>
+</head>
+<body>
+    <h2>Payment using PayDock Apple Pay Open Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.ApplePayOpenWalletButton(
+        "#widget",
+        publicKeyOrAccessToken,
+        serviceId,
+        {
+            amount: 100,
+            currency: "AUD",
+            country: "AU",
+            amount_label: "TOTAL",
+            store_name: "My Store",
+            request_shipping: true,
+            request_payer_name: true,
+            request_payer_email: true,
+            request_payer_phone: true,
+            show_billing_address: true,
+            style: {
+                button_type: 'buy',
+                button_style: 'black'
+            },
+            shipping_options: [
+                {
+                    id: "standard",
+                    label: "Standard Shipping",
+                    detail: "Arrives in 5 to 7 days",
+                    amount: 5.00,
+                    date_components_range: {
+                        start_date_components: {
+                            years: 0,
+                            months: 0,
+                            days: 5,
+                            hours: 0,
+                        },
+                        end_date_components: {
+                            years: 0,
+                            months: 0,
+                            days: 7,
+                            hours: 0,
+                        }
+                    }
+                },
+                {
+                    id: "express",
+                    label: "Express Shipping",
+                    detail: "Arrives in 1 to 2 days",
+                    amount: 15.00,
+                    date_components_range: {
+                        start_date_components: {
+                            years: 0,
+                            months: 0,
+                            days: 1,
+                            hours: 0,
+                        },
+                        end_date_components: {
+                            years: 0,
+                            months: 0,
+                            days: 2,
+                            hours: 0,
+                        }
+                    }
+                }
+            ],
+            apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable']
+        }
+    );
+    button.setEnv('sandbox');
+    button.onUnavailable((data) => {
+        console.log("Apple Pay not available:", data);
+        // Show alternative payment methods
+    });
+    button.onClick((data) => {
+        console.log("Apple Pay button clicked");
+        // Perform pre-payment validation
+    });
+    button.onSuccess((data) => {
+        console.log("Payment successful:", data);
+        // Process the OTT token on your backend
+        processPayment(data.token);
+    });
+    button.onError((data) => {
+        console.error("Payment error:", data);
+        // Handle error appropriately
+    });
+    button.onCancel((data) => {
+        console.log("Payment cancelled");
+        // Handle cancellation
+    });
+    button.onShippingAddressChange(async (addressData) => {
+        // Update shipping costs based on address
+        const response = await updateShippingCosts(addressData);
+        return {
+            amount: response.newAmount,
+            shipping_options: response.shippingOptions
+        };
+    });
+    button.onShippingOptionsChange(async (optionData) => {
+        // Update total based on selected shipping option
+        const response = await updateTotal(optionData);
+        return {
+            amount: response.newAmount
+        };
+    });
+    button.load();
+    async function updateShippingCosts(addressData) {
+        // Your shipping calculation logic based on address
+        const baseAmount = 100;
+        const updatedShippingOptions = [
+            {
+                id: "updated-standard",
+                label: "Updated Standard Shipping",
+                detail: "Based on your location",
+                amount: 8.00
+            },
+            {
+                id: "updated-express",
+                label: "Updated Express Shipping",
+                detail: "Fast delivery to your area",
+                amount: 18.00
+            }
+        ];
+        return {
+            newAmount: baseAmount + updatedShippingOptions[0].amount,
+            shippingOptions: updatedShippingOptions
+        };
+    }
+    async function updateTotal(optionData) {
+        // Your total calculation logic
+        const baseAmount = 100;
+        const shippingAmount = optionData.amount || optionData.data?.amount;
+        return {
+            newAmount: baseAmount + shippingAmount
+        };
+    }
+    function processPayment(ottToken) {
+        // Send OTT token to your backend for payment processing
+        fetch('/api/process-payment', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ott_token: ottToken })
+        });
+    }
+</script>
+</html>
+```
+### Apple Pay with Shipping
+For Apple Pay with shipping enabled:
+```javascript
+let button = new paydock.ApplePayOpenWalletButton(
+    "#widget",
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: "AUD",
+        country: "AU",
+        amount_label: "TOTAL",
+        store_name: "My Store",
+        request_shipping: true,
+        shipping_editing_mode: 'available',
+        required_shipping_contact_fields: [
+            'postalAddress',
+            'name',
+            'phone',
+            'email',
+        ],
+        shipping_options: [
+            {
+                id: "standard",
+                label: "Standard Shipping",
+                detail: "5-7 business days",
+                amount: 5.00
+            },
+            {
+                id: "express",
+                label: "Express Shipping",
+                detail: "1-2 business days",
+                amount: 15.00
+            }
+        ],
+        apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable']
+    }
+);
+button.load();
+```
+When supporting shipping, the methods `onShippingAddressChange` and `onShippingOptionsChange` are required to update the shipping address and options.
+```javascript
+button.onShippingAddressChange(async function(data) {
+    console.log("Shipping address has been updated", data);
+    // Call your backend to recalculate shipping
+    return {
+        amount: newAmount,
+        shipping_options: updatedShippingOptions
+    };
+});
+button.onShippingOptionsChange(async function(data) {
+    console.log("Shipping option selected", data);
+    // Update total based on selected shipping option
+    return {
+        amount: newTotalAmount
+    };
+});
+```
+### Supported Shipping Cases
+#### Injected Shipping Address, non-editable by the customer
+This is the case where the shipping address is injected by the merchant and is not editable by the customer. The customer can only select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'store_pickup'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'store_pickup',
+    required_shipping_contact_fields: [
+        'postalAddress',
+        'name',
+        'phone',
+        'email',
+    ],
+    shipping: {
+        amount: 5,
+        address_line1: "Address Line 1",
+        address_city: "Test Locality",
+        address_state: "NSW",
+        address_country: "Australia",
+        address_country_code: "AU",
+        address_postcode: "3000",
+        contact: {
+            phone: "+61400245562",
+            email: "test@example.com",
+            first_name: "QA",
+            last_name: "QA",
+        },
+        options: [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+            }
+        ],
+    },
+}
+```
+#### Injected Shipping Address, editable by the customer
+This is the case where the shipping address is injected by the merchant and is editable by the customer. The customer can edit the shipping address and select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'available'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'available',
+    required_shipping_contact_fields: [
+        'postalAddress',
+        'name',
+        'phone',
+        'email',
+    ],
+    shipping: {
+        amount: 5,
+        address_line1: "Address Line 1",
+        address_city: "Test Locality",
+        address_state: "NSW",
+        address_country: "Australia",
+        address_country_code: "AU",
+        address_postcode: "3000",
+        contact: {
+            phone: "+61400245562",
+            email: "test@example.com",
+            first_name: "QA",
+            last_name: "QA",
+        },
+        options: [
+            {
+                label: "Test 1",
+                detail: "This is a test 1 shipping methods",
+                amount: 10,
+                id: "randomId1",
+            }
+        ],
+    },
+}
+```
+#### Shipping address editable by the customer (no pre-filled address)
+This is the case where the shipping address is not injected by the merchant and is editable by the customer. The customer can edit the shipping address and select the shipping option.
+The required meta parameters for this case are:
+- shipping_editing_mode: 'available'
+- required_shipping_contact_fields: ['postalAddress'] <-- At least one of the fields is required so the shipping address is shown at Apple Pay.
+```javascript
+meta: {
+    apple_pay_capabilities: ['credentials_available', 'credentials_status_unknown', 'credentials_unavailable'],
+    amount_label: 'TOTAL',
+    country: 'AU',
+    currency: 'AUD',
+    amount: 10,
+    shipping_editing_mode: 'available',
+    required_shipping_contact_fields: [
+        'postalAddress',
+        'name',
+        'phone',
+        'email',
+    ],
+}
+```
+#### No shipping address
+This is the case where no shipping address is required at all in the popup (e.g., digital goods, services, or virtual products, or Shipping Address collected separately by the merchant). The "Send to" UI field will not be shown in the Apple Pay sheet, it will be hidden.
+**Important:**
+- No shipping address should be provided in the meta object.
+- Shipping address could be provided in the initial POST `/v1/charges/wallet` endpoint, if collected previously.
+The required meta parameters for this case are:
+- `required_shipping_contact_fields`: Only include contact fields if needed (phone, email), but NOT `postalAddress`.
+```javascript
+meta: {
+    amount_label: "TOTAL",
+    country: "AU",
+    currency: "AUD",
+    amount: 10,
+    shipping_editing_mode: "available",
+    required_shipping_contact_fields: ["phone", "email"],
+    apple_pay_capabilities: ["credentials_available", "credentials_status_unknown", "credentials_unavailable"]
+}
+```
+## Google Pay Open Wallet Button
+### Initialization
+```javascript
+let button = new paydock.GooglePayOpenWalletButton(
+    "#widget",
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: "AUD",
+        country: "AU",
+        merchant_name: "Your Store",
+    }
+);
+button.load();
+```
+```javascript
+// ES2015 | TypeScript
+import { GooglePayOpenWalletButton } from '@paydock/client-sdk';
+var button = new GooglePayOpenWalletButton(
+    '#widget',
+    publicKeyOrAccessToken,
+    serviceId,
+    {
+        amount: 100,
+        currency: 'AUD',
+        country: 'AU',
+        merchant_name: 'Your Store',
+    }
+);
+button.load();
+```
+### Constructor Parameters
+The GooglePayOpenWalletButton constructor accepts the following parameters:
+1. **selector** (string): CSS selector for the container element
+2. **publicKeyOrAccessToken** (string): Your PayDock public key or access token
+3. **serviceId** (string): The Google Pay service ID configured in PayDock dashboard
+4. **meta** (GooglePayOpenWalletMeta): Google Pay-specific configuration object
+> **Note:** Required meta fields (`amount`, `currency`, `country`) are validated automatically by the `GooglePayOpenWalletButton` class. You do not need to specify them manually.
+### Full Google Pay Example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Google Pay with Open Wallets</title>
+</head>
+<body>
+    <h2>Payment using PayDock Google Pay Open Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.GooglePayOpenWalletButton(
+        "#widget",
+        publicKeyOrAccessToken,
+        serviceId,
+        {
+            amount: 100,
+            currency: "AUD",
+            country: "AU",
+            amount_label: "Total",
+            request_shipping: true,
+            show_billing_address: true,
+            merchant_name: 'Test Merchant',
+            style: {
+                button_type: 'buy',
+                button_color: 'default',
+                button_size_mode: 'fill'
+            },
+            shipping_options: [
+                {
+                    id: "standard",
+                    label: "Standard Shipping",
+                    detail: "Arrives in 5 to 7 days",
+                    amount: 5.00,
+                    type: "ELECTRONIC"
+                },
+                {
+                    id: "express",
+                    label: "Express Shipping",
+                    detail: "Arrives in 1 to 2 days",
+                    amount: 15.00,
+                    type: "PICKUP"
+                }
+            ]
+        }
+    );
+    button.setEnv('sandbox');
+    // Required handlers
+    button.onSuccess((data) => {
+        console.log("Payment successful:", data);
+        processPayment(data.token);
+    });
+    button.onShippingAddressChange(async (addressData) => {
+        const response = await updateShippingCosts(addressData);
+        return {
+            amount: response.newAmount,
+            shipping_options: response.shippingOptions
+        };
+    });
+    button.onShippingOptionsChange(async (optionData) => {
+        const response = await updateTotal(optionData);
+        return {
+            amount: response.newAmount
+        };
+    });
+    // Optional handlers
+    button.onUnavailable((data) => {
+        console.log("Google Pay not available:", data);
+        // Show alternative payment methods
+    });
+    button.onError((data) => {
+        console.error("Payment error:", data);
+        // Handle error appropriately
+    });
+    button.onCancel((data) => {
+        console.log("Payment cancelled");
+        // Handle cancellation
+    });
+    button.onClick((data) => {
+        console.log("Google Pay button clicked");
+        // Perform pre-payment validation
+    });
+    button.load();
+    // Helper functions
+    async function updateShippingCosts(addressData) {
+        const baseAmount = 100;
+        const updatedShippingOptions = [
+            {
+                id: "updated-standard",
+                label: "Updated Standard Shipping",
+                detail: "Based on your location",
+                amount: 8.00,
+                type: "ELECTRONIC"
+            },
+            {
+                id: "updated-express",
+                label: "Updated Express Shipping",
+                detail: "Fast delivery to your area",
+                amount: 18.00,
+                type: "PICKUP"
+            }
+        ];
+        return {
+            newAmount: baseAmount + updatedShippingOptions[0].amount,
+            shippingOptions: updatedShippingOptions
+        };
+    }
+    async function updateTotal(optionData) {
+        const baseAmount = 100;
+        const shippingAmount = optionData.amount || optionData.data?.amount;
+        return {
+            newAmount: baseAmount + shippingAmount
+        };
+    }
+    function processPayment(ottToken) {
+        fetch('/api/process-payment', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ott_token: ottToken })
+        });
+    }
+</script>
+</html>
+```
+## Common API
+Both `ApplePayOpenWalletButton` and `GooglePayOpenWalletButton` share the same event handler API inherited from the base class.
+### Checking for button availability
+If the customer's browser is not supported, or the customer does not have any card added to their wallet, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.
+```javascript
+button.onUnavailable((data) => console.log("No wallet button available", data));
+```
+### Service type validation
+Each button validates that the service configuration matches its expected wallet type. If you use an Apple Pay service ID with `GooglePayOpenWalletButton` (or vice versa), an error will be emitted via `onError`:
+```javascript
+// This will raise an error if the service ID does not correspond to a Google Pay service
+let button = new paydock.GooglePayOpenWalletButton(
+    "#widget",
+    publicKeyOrAccessToken,
+    applePayServiceId, // Wrong! This is an Apple Pay service ID
+    meta
+);
+button.onError((data) => {
+    // Error: Service configuration type 'ApplePay' does not match expected wallet type 'google'.
+    console.error(data.error.message);
+});
+button.load();
+```
+### Performing actions when the wallet button is clicked
+You can perform validations or actions when the user clicks on the wallet button. The callback supports both synchronous and asynchronous operations using the `attachResult` method.
+```javascript
+// Synchronous example
+button.onClick((data) => {
+    console.log("Perform actions on button click");
+    // Perform validation logic
+    // Optionally use attachResult to control flow
+    data.attachResult(true); // Continue with payment
+    // data.attachResult(false); // Halt payment
+});
+// Asynchronous example
+button.onClick((data) => {
+    // Attach a Promise to control the wallet flow
+    data.attachResult(
+        fetch('/api/validate-order')
+            .then(response => response.json())
+            .then(result => {
+                if (!result.valid) {
+                    throw new Error('Order validation failed');
+                }
+                return result;
+            })
+    );
+});
+```
+### Handling successful OTT creation
+When the One Time Token (OTT) is successfully created, the onSuccess callback will be called with the token data. **This callback is required** - if no handler is provided, an error will be thrown.
+```javascript
+button.onSuccess((data) => {
+    console.log("OTT created successfully:", data.token);
+    console.log("Amount:", data.amount);
+    console.log("Shipping:", data.shipping);
+    console.log("Billing:", data.billing);
+    // Use the OTT token to complete payment on your backend
+    fetch('/api/process-payment', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ott_token: data.token })
+    });
+});
+```
+**Important**: The `onSuccess` event handler is mandatory. Not providing one will result in an error.
+### Updating meta after initialization
+If the screen where the button is rendered allows for cart/amount changes, call `setMeta` method to update the meta information. The `setMeta` method is fully typed for each wallet:
+```javascript
+// For Apple Pay - accepts ApplePayOpenWalletMeta
+applePayButton.setMeta({ ...meta, amount: 29.99, amount_label: 'NEW TOTAL' });
+// For Google Pay - accepts GooglePayOpenWalletMeta
+googlePayButton.setMeta({ ...meta, amount: 29.99, merchant_name: 'Updated Store' });
+```
+### Handling errors
+Register a callback function to handle errors that occur during wallet operations, including service type mismatches.
+```javascript
+button.onError((data) => {
+    console.error("Open Wallet error:", data.error);
+    console.log("Error context:", data.context);
+    // Show user-friendly error message
+    showErrorMessage("Payment initialization failed. Please try again.");
+});
+```
+### Handling checkout cancellation
+When the user cancels or closes the wallet payment interface, you can perform cleanup operations.
+```javascript
+button.onCancel((data) => {
+    console.log("Wallet checkout cancelled", data);
+    // Perform cleanup or redirect user
+    window.location.href = '/checkout';
+});
+```
+### Cleaning up
+Remove the wallet button from the DOM when it is no longer needed:
+```javascript
+button.destroy();
+```
+### Events
+The above events can be used in a more generic way via the `eventEmitter.subscribe` method internally, but the recommended approach is to use the dedicated event handler methods provided by the button classes.
+**Available Event Handler Methods:**
+- `onClick(handler)` - Button click events (supports attachResult for flow control)
+- `onSuccess(handler)` - **Required** - OTT creation success events
+- `onUnavailable(handler)` - Wallet unavailable events (supports Promise pattern)
+- `onError(handler)` - Error events (supports Promise pattern)
+- `onCancel(handler)` - Checkout cancellation events (supports Promise pattern)
+- `onLoaded(handler)` - Button loaded/rendered events
+- `onShippingAddressChange(handler)` - **Required for shipping** - Address change events
+- `onShippingOptionsChange(handler)` - **Required for shipping options** - Option change events
+**Event Handler Patterns:**
+```javascript
+// Required handlers (will throw error if not provided)
+button.onSuccess(handler);  // Always required
+button.onShippingAddressChange(handler);  // Required when shipping enabled
+button.onShippingOptionsChange(handler);  // Required when shipping options provided
+// Optional handlers with Promise support
+button.onUnavailable(handler);  // or await button.onUnavailable()
+button.onError(handler);        // or await button.onError()
+button.onCancel(handler);       // or await button.onCancel()
+// Click handler with flow control
+button.onClick(handler);  // Use data.attachResult() for async operations
+// Loaded handler
+button.onLoaded(handler);  // Notified when button renders
+```
+### Apple Pay-Specific Meta Properties
+A full description of the [ApplePayOpenWalletMeta](#ApplePayOpenWalletMeta) properties:
+**Required:**
+- `amount`: The payment amount (number)
+- `currency`: The currency code (string, e.g., "AUD")
+- `country`: The country code (string, e.g., "AU")
+- `amount_label`: Label for the total amount (string)
+- `store_name`: Merchant store name (string)
+**Optional:**
+- `request_shipping?: boolean`: Enable shipping address collection
+- `shipping_options?: IApplePayShippingOption[]`: Array of shipping options
+- `show_billing_address?: boolean`: Show billing address fields
+- `apple_pay_capabilities?: string[]`: Device capabilities
+- `merchant_capabilities?: string[]`: Merchant capabilities
+- `supported_networks?: string[]`: Supported payment networks
+- `required_billing_contact_fields?: string[]`: Required billing contact fields
+- `required_shipping_contact_fields?: string[]`: Required shipping contact fields
+- `supported_countries?: string[]`: Supported countries
+- `shipping_editing_mode?: 'available' | 'store_pickup'`: Shipping address editing mode
+- `style?: { button_type?: ApplePayButtonType, button_style?: ApplePayButtonStyle }`: Button styling
+### Google Pay-Specific Meta Properties
+A full description of the [GooglePayOpenWalletMeta](#GooglePayOpenWalletMeta) properties:
+**Required:**
+- `amount`: The payment amount (number)
+- `currency`: The currency code (string, e.g., "AUD")
+- `country`: The country code (string, e.g., "AU")
+**Optional:**
+- `amount_label?: string`: Label for the total amount
+- `merchant_name?: string`: Display name for the merchant
+- `request_shipping?: boolean`: Enable shipping address collection
+- `shipping_options?: IGooglePayShippingOption[]`: Array of shipping options
+- `show_billing_address?: boolean`: Show billing address fields
+- `card_config?: GooglePayCardConfig`: Card configuration (auth methods, networks, tokenization)
+- `style?: { button_type?: GooglePayButtonType, button_color?: GooglePayButtonColor, button_size_mode?: GooglePayButtonSizeMode }`: Button styling
+### Shipping Options Format
+```javascript
+shipping_options: [
+    {
+        id: "option_id",           // Unique identifier (string)
+        label: "Option Name",      // Display name (string)
+        detail: "Description",     // Optional description (string)
+        amount: 10.00,            // Shipping cost as number
+        date_components_range: {   // Optional: delivery date range (Apple Pay only)
+            start_date_components: {
+                years: 0,
+                months: 0,
+                days: 5,
+                hours: 0,
+            },
+            end_date_components: {
+                years: 0,
+                months: 0,
+                days: 10,
+                hours: 0,
+            }
+        }
+    }
+]
+```
+**Important**:
+- `amount` should be a **number**, not a string
+- `date_components_range` is optional but provides delivery estimates (Apple Pay only)
+- Updated shipping options returned from event handlers don't require `date_components_range`
+### Environment Setup
+```javascript
+// Always set environment before loading
+button.setEnv('sandbox');
+button.load();
+```
+### Error Handling Best Practices
+```javascript
+button.onError(function(data) {
+    console.error('Full error object:', data);
+    // Check different error properties
+    const errorMessage = data.error?.message ||
+                         data.message ||
+                         'Unknown error occurred';
+    // Handle different error types
+    if (data.context?.operation === 'wallet_operation') {
+        // Handle wallet-specific errors
+        showWalletError(errorMessage);
+    } else {
+        // Handle general errors
+        showGeneralError(errorMessage);
+    }
+});
+```
 # Click To Pay
 ## Overview