@paydock/client-sdk 1.103.1 → 1.103.11-beta

package/README.md

@@ -5248,6 +5248,14 @@ In some situations you may want to forcibly close the checkout so that your user
 button.close();
 ```
 
+### Performing actions when the wallet button is clicked
+
+In some situations you may want to perform some validations or actions when the user clicks on the wallet button, for which you can use this method. Currently supported by Paypal, ApplePay and GooglePay wallets.
+
+```javascript
+button.onClick(() => console.log("Perform actions on button click"));
+```
+
 ### Performing actions when shipping info is updated
 
 In Flypay, Paypal, ApplePay via MPGS and GooglePay via MPGS integrations after each shipping info update the `onUpdate(data)` will be called with the selected shipping address information, plus selected shipping method when applicable for Paypal, ApplePay and GooglePay. Merchants should handle this callback, recalculate shipping costs in their server by analyzing the new data, and submit a backend to backend request to `POST charges/:id` with the new total amount and shipping amount (you can find the documentation of this call in the PayDock API documentation).
@@ -5375,30 +5383,51 @@ _(Required `meta` fields: - . Optional `meta` fields: `request_shipping`, `pay_l
 <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
 <script>
     let button = new paydock.WalletButtons(
-          "#widget",
-          charge_token,
-          {
-               request_shipping: true,
-               pay_later: true,
-               standalone: false,
-               style: {
-                    layout: 'horizontal',
-                    color: 'blue',
-                    shape: 'rect',
-                    label: 'paypal',
-               },
-          }
-     );
+        "#widget",
+        charge_token,
+        {
+            request_shipping: true,
+            pay_later: true,
+            standalone: false,
+            style: {
+                layout: 'horizontal',
+                color: 'blue',
+                shape: 'rect',
+                label: 'paypal',
+            },
+        }
+    );
     button.setEnv('sandbox');
     button.onUnavailable(() => console.log("No wallet buttons available"));
     button.onUpdate((data) => {
-          console.log("Updating amount via a backend to backend call to POST charges/:id");
-          // call `POST charges/:id` to modify charge
-          button.update({ success: true });
-     });
+        console.log("Updating amount via a backend to backend call to POST charges/:id");
+        // call `POST charges/:id` to modify charge
+        button.update({ success: true });
+    });
     button.onPaymentSuccessful((data) => console.log("The payment was successful"));
     button.onPaymentError((data) => console.log("The payment was not successful"));
     button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
+
+    // Example 1: Asynchronous onClick handler
+    const asyncLogic = async () => {
+        // Perform asynchronous logic. Expectation is that a Promise is returned and attached to response via `attachResult`,
+        // and resolve or reject of it will dictate how wallet behaves.
+    }
+
+    button.onClick(({ data: { attachResult } }) => {
+        // Promise is attached to the result. On Paypal, when promise is resolved, the user Journey will continue.
+        // If no promise is attached then the Paypal journey will not depend on the promise being resolved or rejected
+        attachResult(asyncLogic());
+    });
+
+    // Example 2: Synchronous onClick handler
+    // button.onClick(({ data: { attachResult } }) => {
+    //     // Perform synchronous logic
+    //     console.log("Synchronous onClick: Button clicked");
+    //     // Optionally return a boolean flag to halt the operation
+    //     attachResult(false);
+    // });
+
     button.load();
 </script>
 </html>
@@ -5532,6 +5561,7 @@ _(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `ra
     button.onUnavailable(() => console.log("No wallet buttons available"));
     button.onPaymentSuccessful((data) => console.log("The payment was successful"));
     button.onPaymentError((data) => console.log("The payment was not successful"));
+    button.onClick(() => console.log("On WalletButton Click"));
     button.onUpdate((data) => {
         console.log("Updating amount via a backend to backend call to POST charges/:id");
         // call `POST charges/:id` to modify charge
@@ -5564,7 +5594,6 @@ _(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `ra
 Also, for **ApplePay via MPGS** you can initialize the `ApplePayPaymentRequest` with your own values instead of using the default ones. Below you can see an example on how to initialize the `ApplePayPaymentRequest` with the `raw_data_initialization` meta field.
 
 Similarly, for **GooglePay via MPGS** you can initialize the `PaymentMethodSpecification` with your own values instead of using the default ones. Below you can see an example on how to initialize the `PaymentMethodSpecification` with the `raw_data_initialization` meta field.
-
 ### ApplePay and GooglePay via MPGS Raw data initialization example
 
 ```html
@@ -5696,6 +5725,24 @@ Similarly, for **GooglePay via MPGS** you can initialize the `PaymentMethodSpeci
 ## Interfaces
 
 <dl>
+<dt><a href="#IEventData">IEventData</a></dt>
+<dd><p>Interface of data from events.</p>
+</dd>
+<dt><a href="#IWalletPaymentSuccessful">IWalletPaymentSuccessful</a></dt>
+<dd><p>Interface of data from a successful payment result.</p>
+</dd>
+<dt><a href="#IWalletUpdate">IWalletUpdate</a></dt>
+<dd><p>Interface of data from an update event.</p>
+</dd>
+<dt><a href="#IWalletOnClick">IWalletOnClick</a></dt>
+<dd><p>Interface of data from a wallet onClick event.</p>
+</dd>
+<dt><a href="#IWalletUnavailable">IWalletUnavailable</a></dt>
+<dd><p>Interface of data from an unavailable event.</p>
+</dd>
+<dt><a href="#IWalletUpdateData">IWalletUpdateData</a></dt>
+<dd><p>Interface of data for wallet button <code>update</code> call.</p>
+</dd>
 <dt><a href="#IWalletMeta">IWalletMeta</a> : <code>object</code></dt>
 <dd><p>Interface of data used by the wallet checkout and payment proccess.</p>
 </dd>
@@ -5710,6 +5757,100 @@ Similarly, for **GooglePay via MPGS** you can initialize the `PaymentMethodSpeci
 </dd>
 </dl>
 
+<a name="IEventData" id="IEventData" href="#IEventData">&nbsp;</a>
+
+## IEventData
+Interface of data from events.
+
+**Kind**: global interface  
+
+| Param | Type |
+| --- | --- |
+| event | <code>string</code> | 
+| data | <code>void</code> \| [<code>IWalletPaymentSuccessful</code>](#IWalletPaymentSuccessful) \| [<code>IWalletUpdate</code>](#IWalletUpdate) \| [<code>IWalletUnavailable</code>](#IWalletUnavailable) \| [<code>IWalletOnClick</code>](#IWalletOnClick) \| <code>any</code> | 
+
+<a name="IWalletPaymentSuccessful" id="IWalletPaymentSuccessful" href="#IWalletPaymentSuccessful">&nbsp;</a>
+
+## IWalletPaymentSuccessful
+Interface of data from a successful payment result.
+
+**Kind**: global interface  
+
+| Param | Type |
+| --- | --- |
+| id | <code>string</code> | 
+| amount | <code>number</code> | 
+| currency | <code>string</code> | 
+| status | <code>string</code> | 
+| [payer_name] | <code>string</code> | 
+| [payer_email] | <code>string</code> | 
+| [payer_phone] | <code>string</code> | 
+
+<a name="IWalletUpdate" id="IWalletUpdate" href="#IWalletUpdate">&nbsp;</a>
+
+## IWalletUpdate
+Interface of data from an update event.
+
+**Kind**: global interface  
+
+| Param | Type |
+| --- | --- |
+| [wallet_response_code] | <code>string</code> | 
+| [wallet_session_id] | <code>string</code> | 
+| [payment_source] | <code>object</code> | 
+| [payment_source.wallet_payment_method_id] | <code>string</code> | 
+| [payment_source.card_number_last4] | <code>string</code> | 
+| [payment_source.card_scheme] | <code>string</code> | 
+| [wallet_loyalty_account] | <code>object</code> | 
+| [wallet_loyalty_account.id] | <code>string</code> | 
+| [wallet_loyalty_account.barcode] | <code>string</code> | 
+| [shipping] | <code>object</code> | 
+| [shipping.address_line1] | <code>string</code> | 
+| [shipping.address_line2] | <code>string</code> | 
+| [shipping.address_postcode] | <code>string</code> | 
+| [shipping.address_city] | <code>string</code> | 
+| [shipping.address_state] | <code>string</code> | 
+| [shipping.address_country] | <code>string</code> | 
+| [shipping.address_company] | <code>string</code> | 
+| [shipping.post_office_box_number] | <code>string</code> | 
+| [shipping.wallet_address_id] | <code>string</code> | 
+| [shipping.wallet_address_name] | <code>string</code> | 
+| [shipping.wallet_address_created_timestamp] | <code>string</code> | 
+| [shipping.wallet_address_updated_timestamp] | <code>string</code> | 
+
+<a name="IWalletOnClick" id="IWalletOnClick" href="#IWalletOnClick">&nbsp;</a>
+
+## IWalletOnClick
+Interface of data from a wallet onClick event.
+
+**Kind**: global interface  
+
+| Param | Description |
+| --- | --- |
+| attachResult | Method to be called that attaches a result to the wallet onClick operation. When handler is synchronous, this method is optionally called with a boolean flag indicating validation result. When handler executes asynchronous operations, this method must be called with the Promise to have the wallet process wait for its completion or rejection. |
+
+<a name="IWalletUnavailable" id="IWalletUnavailable" href="#IWalletUnavailable">&nbsp;</a>
+
+## IWalletUnavailable
+Interface of data from an unavailable event.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [wallet] | <code>string</code> | For gateways with more than one wallet button available (e.g: MPGS with ApplePay and GooglePay). Possible values for wallet are 'apple' or 'google'. |
+
+<a name="IWalletUpdateData" id="IWalletUpdateData" href="#IWalletUpdateData">&nbsp;</a>
+
+## IWalletUpdateData
+Interface of data for wallet button `update` call.
+
+**Kind**: global interface  
+
+| Param | Type |
+| --- | --- |
+| success | <code>boolean</code> | 
+
 <a name="IWalletMeta" id="IWalletMeta" href="#IWalletMeta">&nbsp;</a>
 
 ## IWalletMeta : <code>object</code>
@@ -5794,14 +5935,19 @@ Class WalletButtons to work with different E-Wallets within html (currently supp
     * [.load()](#WalletButtons+load)
     * [.update()](#WalletButtons+update)
     * [.setEnv(env, [alias])](#WalletButtons+setEnv)
+    * [.enable()](#WalletButtons+enable)
+    * [.disable()](#WalletButtons+disable)
     * [.close()](#WalletButtons+close)
-    * [.on(eventName, [cb])](#WalletButtons+on) ⇒ <code>Promise.&lt;IEventData&gt;</code> \| <code>void</code>
+    * [.on(eventName, [cb])](#WalletButtons+on) ⇒ [<code>Promise.&lt;IEventData&gt;</code>](#IEventData) \| <code>void</code>
     * [.onUnavailable([handler])](#WalletButtons+onUnavailable)
     * [.onUpdate([handler])](#WalletButtons+onUpdate)
     * [.onPaymentSuccessful([handler])](#WalletButtons+onPaymentSuccessful)
     * [.onPaymentInReview([handler])](#WalletButtons+onPaymentInReview)
     * [.onPaymentError([handler])](#WalletButtons+onPaymentError)
     * [.onAuthTokensChanged([handler])](#WalletButtons+onAuthTokensChanged)
+    * [.onClick(handler)](#WalletButtons+onClick)
+    * [.onCheckoutOpen(handler)](#WalletButtons+onCheckoutOpen)
+    * [.onCheckoutClose(handler)](#WalletButtons+onCheckoutClose)
 
 <a name="new_WalletButtons_new" id="new_WalletButtons_new" href="#new_WalletButtons_new">&nbsp;</a>
 
@@ -5912,6 +6058,26 @@ Bear in mind that you must set an environment before calling `button.load()`.
 ```js
 button.setEnv('production', 'paydock.com');
 ```
+<a name="WalletButtons+enable" id="WalletButtons+enable" href="#WalletButtons+enable">&nbsp;</a>
+
+### walletButtons.enable()
+Current method can enable the payment button. This method is only supported for Flypay V2.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+**Example**  
+```js
+button.enable();
+```
+<a name="WalletButtons+disable" id="WalletButtons+disable" href="#WalletButtons+disable">&nbsp;</a>
+
+### walletButtons.disable()
+Current method can disable the payment button. This method is only supported for Flypay V2.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+**Example**  
+```js
+button.disable('production', 'paydock.com');
+```
 <a name="WalletButtons+close" id="WalletButtons+close" href="#WalletButtons+close">&nbsp;</a>
 
 ### walletButtons.close()
@@ -5924,7 +6090,7 @@ button.close();
 ```
 <a name="WalletButtons+on" id="WalletButtons+on" href="#WalletButtons+on">&nbsp;</a>
 
-### walletButtons.on(eventName, [cb]) ⇒ <code>Promise.&lt;IEventData&gt;</code> \| <code>void</code>
+### walletButtons.on(eventName, [cb]) ⇒ [<code>Promise.&lt;IEventData&gt;</code>](#IEventData) \| <code>void</code>
 Listen to events of button. `unavailable` returns no data, `paymentSuccessful` returns IWalletPaymentSuccessful
 for Stripe or full response for Flypay, and `paymentError` an error.
 
@@ -6087,6 +6253,63 @@ button.onAuthTokensChanged().then((eventData) => {
     console.log('Authentication tokens changed:', eventData);
 });
 ```
+<a name="WalletButtons+onClick" id="WalletButtons+onClick" href="#WalletButtons+onClick">&nbsp;</a>
+
+### walletButtons.onClick(handler)
+Registers a callback function to be invoked when the wallet button gets clicked.
+There are two operational modes supported, Synchronous and Asynchronous.
+When asynchronous operations need to occur on the callback handler, attaching the Promise via `attachResult` is required to have the wallet wait for a result.
+When synchronous operations occur on the callback handler, attaching a boolean result via `attachResult` is optional to control the execution flow.
+Note this is supported for Paypal, GooglePay and ApplePay wallet buttons at the moment.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | <code>listener</code> | Function to be called when the wallet button is clicked. |
+
+**Example**  
+```js
+button.onClick((data) => {
+     performValidationLogic();
+});
+```
+<a name="WalletButtons+onCheckoutOpen" id="WalletButtons+onCheckoutOpen" href="#WalletButtons+onCheckoutOpen">&nbsp;</a>
+
+### walletButtons.onCheckoutOpen(handler)
+Registers a callback function to be invoked when the wallet checkout opens.
+Note this is supported for FlypayV2 wallet button at the moment.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | <code>listener</code> | Function to be called when the wallet checkout opens. |
+
+**Example**  
+```js
+button.onCheckoutOpen((data) => {
+     console.log('Checkout opens');
+});
+```
+<a name="WalletButtons+onCheckoutClose" id="WalletButtons+onCheckoutClose" href="#WalletButtons+onCheckoutClose">&nbsp;</a>
+
+### walletButtons.onCheckoutClose(handler)
+Registers a callback function to be invoked when the wallet checkout closes.
+Note this is supported for FlypayV2 wallet button at the moment.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| handler | <code>listener</code> | Function to be called when the wallet checkout closes. |
+
+**Example**  
+```js
+button.onCheckoutClose(() => {
+     console.log('Wallet checkout closes');
+});
+```
 <a name="EVENT" id="EVENT" href="#EVENT">&nbsp;</a>
 
 ## EVENT : <code>object</code>
@@ -6100,6 +6323,7 @@ List of available event's name in the wallet button lifecycle
 | UPDATE | <code>string</code> | <code>&quot;update&quot;</code> | 
 | PAYMENT_SUCCESSFUL | <code>string</code> | <code>&quot;paymentSuccessful&quot;</code> | 
 | PAYMENT_ERROR | <code>string</code> | <code>&quot;paymentError&quot;</code> | 
+| ON_CLICK | <code>string</code> | <code>&quot;onClick&quot;</code> | 
 
 
 ## Secure Remote Commerce