@paydock/client-sdk 1.140.0-beta → 1.141.0-beta

package/README.md

@@ -1977,6 +1977,7 @@ Class ZipmoneyCheckoutButton is wrapper of CheckoutButton transform usual button
     * [new ZipmoneyCheckoutButton(selector, publicKey, [gatewayId], [gatewayId])](#user-content-cb_new_ZipmoneyCheckoutButton_new)
     * [.setSuspendedRedirectUri(string)](#user-content-cb_ZipmoneyCheckoutButton+setSuspendedRedirectUri)
     * [.setRedirectUrl(string)](#user-content-cb_ZipmoneyCheckoutButton+setRedirectUrl)
+    * [.onClick(handler)](#user-content-cb_ZipmoneyCheckoutButton+onClick)
     * [.on(eventName, cb)](#user-content-cb_CheckoutButton+on)
     * [.close()](#user-content-cb_CheckoutButton+close)
     * [.onFinishInsert(selector, dataType)](#user-content-cb_CheckoutButton+onFinishInsert)
@@ -2035,6 +2036,27 @@ The merchant's customer would be automatically redirected to this URL after the
 | --- | --- | --- |
 | string | <code>url</code> | URL for redirect |
 
+<a name="cb_ZipmoneyCheckoutButton+onClick" id="cb_ZipmoneyCheckoutButton+onClick" href="#user-content-cb_ZipmoneyCheckoutButton+onClick">&nbsp;</a>
+
+### zipmoneyCheckoutButton.onClick(handler)
+Subscribe to the click event with an async handler.
+The checkout flow will wait for the async handler to complete before proceeding.
+If the handler resolves to `false`, the checkout flow will be cancelled.
+
+**Kind**: instance method of [<code>ZipmoneyCheckoutButton</code>](#user-content-cb_ZipmoneyCheckoutButton)  
+
+| Param | Description |
+| --- | --- |
+| handler | Async function to be called when the button is clicked |
+
+**Example**  
+
+```javascript
+button.onClick(async () => {
+    const isValid = await fetchDataFromServer();
+    return isValid; // return false to stop checkout
+});
+```
 <a name="cb_CheckoutButton+on" id="cb_CheckoutButton+on" href="#user-content-cb_CheckoutButton+on">&nbsp;</a>
 
 ### zipmoneyCheckoutButton.on(eventName, cb)
@@ -5627,44 +5649,37 @@ button.setEnv('sandbox');
 
     button.setEnv('sandbox');
 
-    button.onUnavailable((data) => {
+    button.onUnavailable(({ data }) => {
         console.log("Apple Pay not available:", data);
-        // Show alternative payment methods
     });
 
-    button.onClick((data) => {
+    button.onClick(() => {
         console.log("Apple Pay button clicked");
-        // Perform pre-payment validation
     });
 
-    button.onSuccess((data) => {
+    button.onSuccess(({ data }) => {
         console.log("Payment successful:", data);
-        // Process the OTT token on your backend
         processPayment(data.token);
     });
 
-    button.onError((data) => {
+    button.onError(({ data }) => {
         console.error("Payment error:", data);
-        // Handle error appropriately
     });
 
-    button.onCancel((data) => {
+    button.onCancel(() => {
         console.log("Payment cancelled");
-        // Handle cancellation
     });
 
-    button.onShippingAddressChange(async (addressData) => {
-        // Update shipping costs based on address
-        const response = await updateShippingCosts(addressData);
+    button.onShippingAddressChange(async ({ data }) => {
+        const response = await updateShippingCosts(data);
         return {
             amount: response.newAmount,
             shipping_options: response.shippingOptions
         };
     });
 
-    button.onShippingOptionsChange(async (optionData) => {
-        // Update total based on selected shipping option
-        const response = await updateTotal(optionData);
+    button.onShippingOptionsChange(async ({ data }) => {
+        const response = await updateTotal(data);
         return {
             amount: response.newAmount
         };
@@ -5696,17 +5711,15 @@ button.setEnv('sandbox');
         };
     }
 
-    async function updateTotal(optionData) {
-        // Your total calculation logic
+    async function updateTotal(shippingOption) {
         const baseAmount = 100;
-        const shippingAmount = optionData.amount || optionData.data?.amount;
+        const shippingAmount = shippingOption.amount;
         return {
             newAmount: baseAmount + shippingAmount
         };
     }
 
     function processPayment(ottToken) {
-        // Send OTT token to your backend for payment processing
         fetch('/api/process-payment', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -5759,21 +5772,19 @@ let button = new paydock.ApplePayOpenWalletButton(
 button.load();
 ```
 
-When supporting shipping, the methods `onShippingAddressChange` and `onShippingOptionsChange` are required to update the shipping address and options.
+When supporting shipping, registering `onShippingAddressChange` and `onShippingOptionsChange` handlers lets you recalculate totals and update shipping options dynamically. If no handler is registered (or the handler throws), the SDK auto-accepts with the current amount and options.
 
 ```javascript
-button.onShippingAddressChange(async function(data) {
+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) {
+button.onShippingOptionsChange(async function({ data }) {
     console.log("Shipping option selected", data);
-    // Update total based on selected shipping option
     return {
         amount: newTotalAmount
     };
@@ -6027,46 +6038,40 @@ The GooglePayOpenWalletButton constructor accepts the following parameters:
 
     button.setEnv('sandbox');
 
-    // Required handlers
-    button.onSuccess((data) => {
+    button.onSuccess(({ data }) => {
         console.log("Payment successful:", data);
         processPayment(data.token);
     });
 
-    button.onShippingAddressChange(async (addressData) => {
-        const response = await updateShippingCosts(addressData);
+    button.onShippingAddressChange(async ({ data }) => {
+        const response = await updateShippingCosts(data);
         return {
             amount: response.newAmount,
             shipping_options: response.shippingOptions
         };
     });
 
-    button.onShippingOptionsChange(async (optionData) => {
-        const response = await updateTotal(optionData);
+    button.onShippingOptionsChange(async ({ data }) => {
+        const response = await updateTotal(data);
         return {
             amount: response.newAmount
         };
     });
 
-    // Optional handlers
-    button.onUnavailable((data) => {
+    button.onUnavailable(({ data }) => {
         console.log("Google Pay not available:", data);
-        // Show alternative payment methods
     });
 
-    button.onError((data) => {
+    button.onError(({ data }) => {
         console.error("Payment error:", data);
-        // Handle error appropriately
     });
 
-    button.onCancel((data) => {
+    button.onCancel(() => {
         console.log("Payment cancelled");
-        // Handle cancellation
     });
 
-    button.onClick((data) => {
+    button.onClick(() => {
         console.log("Google Pay button clicked");
-        // Perform pre-payment validation
     });
 
     button.load();
@@ -6097,9 +6102,9 @@ The GooglePayOpenWalletButton constructor accepts the following parameters:
         };
     }
 
-    async function updateTotal(optionData) {
+    async function updateTotal(shippingOption) {
         const baseAmount = 100;
-        const shippingAmount = optionData.amount || optionData.data?.amount;
+        const shippingAmount = shippingOption.amount;
         return {
             newAmount: baseAmount + shippingAmount
         };
@@ -6125,7 +6130,7 @@ Both `ApplePayOpenWalletButton` and `GooglePayOpenWalletButton` share the same e
 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));
+button.onUnavailable(({ data }) => console.log("No wallet button available", data));
 ```
 
 ### Service type validation
@@ -6141,7 +6146,7 @@ let button = new paydock.GooglePayOpenWalletButton(
     meta
 );
 
-button.onError((data) => {
+button.onError(({ data }) => {
     // Error: Service configuration type 'ApplePay' does not match expected wallet type 'google'.
     console.error(data.error.message);
 });
@@ -6151,31 +6156,26 @@ 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.
+You can perform validations or actions when the user clicks on the wallet button. The callback supports both synchronous and asynchronous operations using its return value: return `false` to abort, return a `Promise` to defer the wallet sheet, or throw an error to abort.
 
 ```javascript
-// Synchronous example
-button.onClick((data) => {
+// Synchronous — continue normally
+button.onClick(() => {
     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;
-            })
-    );
+// Synchronous — return false to abort the payment flow
+button.onClick(() => {
+    if (!isOrderValid()) return false;
+});
+
+// Asynchronous — defer the wallet sheet until the promise resolves
+button.onClick(async () => {
+    const response = await fetch('/api/validate-order');
+    const result = await response.json();
+    if (!result.valid) {
+        throw new Error('Order validation failed');
+    }
 });
 ```
 
@@ -6184,13 +6184,12 @@ button.onClick((data) => {
 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) => {
+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' },
@@ -6218,11 +6217,10 @@ googlePayButton.setMeta({ ...meta, amount: 29.99, merchant_name: 'Updated Store'
 Register a callback function to handle errors that occur during wallet operations, including service type mismatches.
 
 ```javascript
-button.onError((data) => {
+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.");
 });
 ```
@@ -6232,10 +6230,8 @@ button.onError((data) => {
 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
+button.onCancel(() => {
+    console.log("Wallet checkout cancelled");
     window.location.href = '/checkout';
 });
 ```
@@ -6252,22 +6248,24 @@ button.destroy();
 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)
+- `onClick(handler)` - Button click events (return `false` to abort, `Promise` to defer)
 - `onSuccess(handler)` - **Required** - OTT creation success events
 - `onUnavailable(handler)` - Wallet unavailable events (supports Promise pattern)
 - `onError(handler)` - Error events (supports Promise pattern)
 - `onCancel(handler)` - Checkout cancellation events (supports Promise pattern)
 - `onLoaded(handler)` - Button loaded/rendered events
-- `onShippingAddressChange(handler)` - **Required for shipping** - Address change events
-- `onShippingOptionsChange(handler)` - **Required for shipping options** - Option change events
+- `onShippingAddressChange(handler)` - **Recommended for shipping** - Address change events (auto-accepted if not registered)
+- `onShippingOptionsChange(handler)` - **Recommended for shipping options** - Option change events (auto-accepted if not registered)
 
 **Event Handler Patterns:**
 
 ```javascript
-// Required handlers (will throw error if not provided)
+// Required handler
 button.onSuccess(handler);  // Always required
-button.onShippingAddressChange(handler);  // Required when shipping enabled
-button.onShippingOptionsChange(handler);  // Required when shipping options provided
+
+// Recommended when shipping is enabled (auto-accepted if not registered)
+button.onShippingAddressChange(handler);
+button.onShippingOptionsChange(handler);
 
 // Optional handlers with Promise support
 button.onUnavailable(handler);  // or await button.onUnavailable()
@@ -6275,7 +6273,7 @@ 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
+button.onClick(handler);  // Return false to abort, or a Promise to defer
 
 // Loaded handler
 button.onLoaded(handler);  // Notified when button renders
@@ -6363,20 +6361,14 @@ button.load();
 
 ### Error Handling Best Practices
 ```javascript
-button.onError(function(data) {
+button.onError(function({ data }) {
     console.error('Full error object:', data);
 
-    // Check different error properties
-    const errorMessage = data.error?.message ||
-                         data.message ||
-                         'Unknown error occurred';
+    const errorMessage = data.error?.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);
     }
 });