@paydock/client-sdk 1.113.2 → 1.114.7-beta

package/docs/paypal-save-payment-source.md

@@ -0,0 +1,256 @@
+## Classes
+
+<dl>
+<dt><a href="#PayPalSavePaymentSourceWidget">PayPalSavePaymentSourceWidget</a></dt>
+<dd><p>PayPal Save Payment Source Widget constructor</p>
+</dd>
+</dl>
+
+## Typedefs
+
+<dl>
+<dt><a href="#OnSuccessCallback">OnSuccessCallback</a> : <code>function</code></dt>
+<dd><p>Callback for onSuccess method.</p>
+</dd>
+<dt><a href="#OnErrorCallback">OnErrorCallback</a> : <code>function</code></dt>
+<dd><p>Callback for onError method.</p>
+</dd>
+<dt><a href="#OnCancelCallback">OnCancelCallback</a> : <code>function</code></dt>
+<dd><p>Callback for onCancel method.</p>
+</dd>
+</dl>
+
+## Interfaces
+
+<dl>
+<dt><a href="#PayPalSavePaymentSourceWidgetConfig">PayPalSavePaymentSourceWidgetConfig</a> : <code>object</code></dt>
+<dd><p>Interface of data used for PayPal configuration. For further information refer to <a href="https://developer.paypal.com/sdk/js/reference/#style">the documentation</a>.</p>
+</dd>
+<dt><a href="#ErrorCodes">ErrorCodes</a> : <code>object</code></dt>
+<dd><p>Interface of possible error codes inside onError event data.</p>
+</dd>
+<dt><a href="#IOnSuccessEventData">IOnSuccessEventData</a> : <code>object</code></dt>
+<dd><p>Interface for IOnSuccessEventData</p>
+</dd>
+<dt><a href="#IOnErrorEventData">IOnErrorEventData</a> : <code>object</code></dt>
+<dd><p>Interface for IOnErrorEventData</p>
+</dd>
+<dt><a href="#IOnCancelEventData">IOnCancelEventData</a> : <code>object</code></dt>
+<dd><p>Interface for IOnCancelEventData</p>
+</dd>
+</dl>
+
+<a name="PayPalSavePaymentSourceWidgetConfig" id="PayPalSavePaymentSourceWidgetConfig" href="#PayPalSavePaymentSourceWidgetConfig">&nbsp;</a>
+
+## PayPalSavePaymentSourceWidgetConfig : <code>object</code>
+Interface of data used for PayPal configuration. For further information refer to [the documentation](https://developer.paypal.com/sdk/js/reference/#style).
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [style.layout] | <code>&#x27;vertical&#x27;</code> \| <code>&#x27;horizontal&#x27;</code> | Used for indicating the PayPal Button layout. |
+| [style.color] | <code>&#x27;blue&#x27;</code> \| <code>&#x27;gold&#x27;</code> \| <code>&#x27;silver&#x27;</code> \| <code>&#x27;black&#x27;</code> \| <code>&#x27;white&#x27;</code> | Used for indicating the main color of the PayPal Button. |
+| [style.shape] | <code>&#x27;rect&#x27;</code> \| <code>&#x27;sharp&#x27;</code> \| <code>&#x27;pill&#x27;</code> | Used for indicating the shape of the PayPal Button. |
+| [style.label] | <code>&#x27;paypal&#x27;</code> \| <code>&#x27;checkout&#x27;</code> \| <code>&#x27;buynow&#x27;</code> \| <code>&#x27;pay&#x27;</code> | Used for indicating the label of the PayPal Button. |
+| [style.disableMaxWidth] | <code>boolean</code> | Used for indicating if the max width will be disabled. |
+| [style.disableMaxHeight] | <code>boolean</code> | Used for indicating the max height will be disabled. |
+| [style.height] | <code>number</code> | Used for indicating the height of the PayPal Button, if disableMaxHeight is true. |
+| [style.borderRadius] | <code>number</code> | Used for indicating the border radius of the PayPal Button. |
+| [style.tagline] | <code>boolean</code> | Used for indicating the tagline of the PayPal Button. |
+| [message.amount] | <code>number</code> | Used for indicating an amount before the payment. |
+| [message.align] | <code>&#x27;center&#x27;</code> \| <code>&#x27;left&#x27;</code> \| <code>&#x27;right&#x27;</code> | Used for indicating the align of the message. |
+| [message.color] | <code>&#x27;black&#x27;</code> \| <code>&#x27;white&#x27;</code> | Used for indicating the color of the message. |
+| [message.position] | <code>&#x27;top&#x27;</code> \| <code>&#x27;bottom&#x27;</code> | Used for indicating the position of the message. |
+
+<a name="ErrorCodes" id="ErrorCodes" href="#ErrorCodes">&nbsp;</a>
+
+## ErrorCodes : <code>object</code>
+Interface of possible error codes inside onError event data.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [unavailable] | <code>string</code> | Error code when an error occurs loading the widget. |
+| [onPaypalVaultSetupTokenError] | <code>string</code> | Error code when an error occrus on PayPal side. |
+| [onGetIdTokenError] | <code>string</code> | Error code when trying to get ID token from PayPal. |
+| [onGetWalletConfigError] | <code>string</code> | Error code when trying to get wallet config from Paydock. |
+| [onGetSetupTokenError] | <code>string</code> | Error code when trying to get the setup token from PayPal. |
+| [onOneTimeTokenError] | <code>string</code> | Error code when trying to get the one time token from Paydock. |
+
+<a name="IOnSuccessEventData" id="IOnSuccessEventData" href="#IOnSuccessEventData">&nbsp;</a>
+
+## IOnSuccessEventData : <code>object</code>
+Interface for IOnSuccessEventData
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>EVENTS</code> | Event Name is 'ON_SUCCESS' |
+| data | <code>object</code> | Data object |
+| data.token | <code>string</code> | One Time Token to be exchanged for a Paydock Customer. |
+| [data.email] | <code>string</code> | Paypal account customer email if retrieved from Paypal servers. |
+
+<a name="IOnErrorEventData" id="IOnErrorEventData" href="#IOnErrorEventData">&nbsp;</a>
+
+## IOnErrorEventData : <code>object</code>
+Interface for IOnErrorEventData
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>EVENTS</code> | Event Name is 'ON_ERROR' |
+| data | <code>object</code> | Error data object |
+| data.error_code | [<code>ErrorCodes</code>](#ErrorCodes) | Error code. One of ErrorCodes. |
+| [data.details] | <code>string</code> | Error details. |
+| [data.message] | <code>string</code> | Error message. |
+
+<a name="IOnCancelEventData" id="IOnCancelEventData" href="#IOnCancelEventData">&nbsp;</a>
+
+## IOnCancelEventData : <code>object</code>
+Interface for IOnCancelEventData
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>EVENTS</code> | Event Name is 'ON_CANCEL' |
+
+<a name="PayPalSavePaymentSourceWidget" id="PayPalSavePaymentSourceWidget" href="#PayPalSavePaymentSourceWidget">&nbsp;</a>
+
+## PayPalSavePaymentSourceWidget
+PayPal Save Payment Source Widget constructor
+
+**Kind**: global class  
+
+* [PayPalSavePaymentSourceWidget](#PayPalSavePaymentSourceWidget)
+    * [new PayPalSavePaymentSourceWidget(selector, publicKey, gatewayId, config)](#new_PayPalSavePaymentSourceWidget_new)
+    * [.load()](#PayPalSavePaymentSourceWidget+load)
+    * [.setEnv(env, [alias])](#PayPalSavePaymentSourceWidget+setEnv)
+    * [.onSuccess([callback])](#PayPalSavePaymentSourceWidget+onSuccess)
+    * [.onError([callback])](#PayPalSavePaymentSourceWidget+onError)
+    * [.onCancel([callback])](#PayPalSavePaymentSourceWidget+onCancel)
+
+<a name="new_PayPalSavePaymentSourceWidget_new" id="new_PayPalSavePaymentSourceWidget_new" href="#new_PayPalSavePaymentSourceWidget_new">&nbsp;</a>
+
+### new PayPalSavePaymentSourceWidget(selector, publicKey, gatewayId, config)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| selector | <code>string</code> | Selector of html element. Container for PayPal Save Payment Source Widget. |
+| publicKey | <code>string</code> | PayDock users public key. |
+| gatewayId | <code>string</code> | PayDock's PayPal gatewayId. |
+| config | [<code>PayPalSavePaymentSourceWidgetConfig</code>](#PayPalSavePaymentSourceWidgetConfig) | Extra configuration for the widget, like styles. |
+
+**Example**  
+```js
+var payPalSavePaymentSourceWidget = new PayPalSavePaymentSourceWidget('#paypalButton', 'public_key', 'gateway_id');
+```
+<a name="PayPalSavePaymentSourceWidget+load" id="PayPalSavePaymentSourceWidget+load" href="#PayPalSavePaymentSourceWidget+load">&nbsp;</a>
+
+### payPalSavePaymentSourceWidget.load()
+The final method after configuring the PayPalSavePaymentSource Widget to
+start the load process.
+
+**Kind**: instance method of [<code>PayPalSavePaymentSourceWidget</code>](#PayPalSavePaymentSourceWidget)  
+<a name="PayPalSavePaymentSourceWidget+setEnv" id="PayPalSavePaymentSourceWidget+setEnv" href="#PayPalSavePaymentSourceWidget+setEnv">&nbsp;</a>
+
+### payPalSavePaymentSourceWidget.setEnv(env, [alias])
+Current method can change environment. By default environment = sandbox.
+Also we can change domain alias for this environment. By default domain_alias = paydock.com
+
+**Kind**: instance method of [<code>PayPalSavePaymentSourceWidget</code>](#PayPalSavePaymentSourceWidget)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| env | <code>string</code> | sandbox, production |
+| [alias] | <code>string</code> | Own domain alias |
+
+**Example**  
+```js
+payPalSavePaymentSourceWidget.setEnv('production');
+```
+<a name="PayPalSavePaymentSourceWidget+onSuccess" id="PayPalSavePaymentSourceWidget+onSuccess" href="#PayPalSavePaymentSourceWidget+onSuccess">&nbsp;</a>
+
+### payPalSavePaymentSourceWidget.onSuccess([callback])
+If the setup token was successfully approved and a OTT was generated, the function passed as parameter will be called.
+Important: Do not perform thread blocking operations in callback such as window.alert() calls.
+
+**Kind**: instance method of [<code>PayPalSavePaymentSourceWidget</code>](#PayPalSavePaymentSourceWidget)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [callback] | [<code>OnSuccessCallback</code>](#OnSuccessCallback) | Function to be called when the result is successful. |
+
+**Example**  
+```js
+payPalSavePaymentSourceWidget.onSuccess((eventData) => console.log('One time token and email obtained successfully'));
+```
+<a name="PayPalSavePaymentSourceWidget+onError" id="PayPalSavePaymentSourceWidget+onError" href="#PayPalSavePaymentSourceWidget+onError">&nbsp;</a>
+
+### payPalSavePaymentSourceWidget.onError([callback])
+If in the process for obtaining the setup token fails, the function passed as parameter will be called.
+Important: Do not perform thread blocking operations in callback such as window.alert() calls.
+
+**Kind**: instance method of [<code>PayPalSavePaymentSourceWidget</code>](#PayPalSavePaymentSourceWidget)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [callback] | [<code>OnErrorCallback</code>](#OnErrorCallback) | Function to be called when there is an error in the flow. |
+
+**Example**  
+```js
+payPalSavePaymentSourceWidget.onError((eventData) => console.log('Some error occurred'));
+```
+<a name="PayPalSavePaymentSourceWidget+onCancel" id="PayPalSavePaymentSourceWidget+onCancel" href="#PayPalSavePaymentSourceWidget+onCancel">&nbsp;</a>
+
+### payPalSavePaymentSourceWidget.onCancel([callback])
+If in the process for obtaining the setup token was cancelled, the function passed as parameter will be called.
+Important: Do not perform thread blocking operations in callback such as window.alert() calls.
+
+**Kind**: instance method of [<code>PayPalSavePaymentSourceWidget</code>](#PayPalSavePaymentSourceWidget)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [callback] | [<code>OnCancelCallback</code>](#OnCancelCallback) | Function to be called when the operation is cancelled. |
+
+**Example**  
+```js
+payPalSavePaymentSourceWidget.onCancel(() => console.log('Operation cancelled'));
+```
+<a name="OnSuccessCallback" id="OnSuccessCallback" href="#OnSuccessCallback">&nbsp;</a>
+
+## OnSuccessCallback : <code>function</code>
+Callback for onSuccess method.
+
+**Kind**: global typedef  
+
+| Param | Type |
+| --- | --- |
+| data | [<code>IOnSuccessEventData</code>](#IOnSuccessEventData) | 
+
+<a name="OnErrorCallback" id="OnErrorCallback" href="#OnErrorCallback">&nbsp;</a>
+
+## OnErrorCallback : <code>function</code>
+Callback for onError method.
+
+**Kind**: global typedef  
+
+| Param | Type |
+| --- | --- |
+| data | [<code>IOnErrorEventData</code>](#IOnErrorEventData) | 
+
+<a name="OnCancelCallback" id="OnCancelCallback" href="#OnCancelCallback">&nbsp;</a>
+
+## OnCancelCallback : <code>function</code>
+Callback for onCancel method.
+
+**Kind**: global typedef  
+
+| Param | Type |
+| --- | --- |
+| data | [<code>IOnCancelEventData</code>](#IOnCancelEventData) | 
+

package/docs/wallet-buttons-examples.md

@@ -425,7 +425,7 @@ _(Required `meta` fields: - . Optional `meta` fields: -)_
         },
 	);
     button.setEnv('sandbox');
-    button.onUnavailable(() => console.log("No wallet buttons available"));
+    button.onUnavailable((data) => 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.onAuthTokensChanged((data) => console.log('Authentication tokens changed'));

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

@@ -63,7 +63,7 @@ A full description of the meta parameters for [ApplePayWalletButtonExpress](#App
         }
     );
 
-    button.setEnv(sandbox);
+    button.setEnv('sandbox');
 
     button.onUnavailable(function() {
         console.log("Button not available");

package/docs/wallet-buttons-express.md

@@ -111,6 +111,7 @@ For in-depth information, please refer to the [Paypal documentation](https://dev
 | amount | <code>number</code> | Total amount of the transaction. Represents the money to be charged. |
 | currency | <code>string</code> | Currency of the transaction in ISO 4217 currency code format. |
 | [pay_later] | <code>boolean</code> | Flag to enable Pay Later feature of PayPal, allowing Pay in 4. Default false. |
+| [hide_message] | <code>boolean</code> | Used to hide Pay Later message in PayPal Smart Checkout WalletButton integration. Optional for [PayPal]. N/A for other wallets. |
 | [standalone] | <code>boolean</code> | Flag to specify if the PayPal standalone button should be used. Default false. |
 | [capture] | <code>boolean</code> | Flag to specify if the transaction amount should be captured immediately or authorized for later capture. Default false. |
 | [style] | <code>object</code> | Styling configurations for the PayPal widget. |

package/docs/wallet-buttons.md

@@ -131,6 +131,8 @@ Interface of data from an unavailable event.
 | 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'. |
+| [type] | <code>string</code> | Event Code. Value can be 'create_order_id_error' on FlypayV2 order creation failure. Optional for [Flypay V2]. N/A for other wallets. |
+| [error_code] | <code>string</code> | Event Error Code. Value can be any error code return from Paydock's API. Optional for [Flypay V2]. N/A for other wallets.  + |
 
 <a name="IWalletUpdateData" id="IWalletUpdateData" href="#IWalletUpdateData">&nbsp;</a>
 
@@ -155,6 +157,7 @@ Interface of data used by the wallet checkout and payment proccess.
 | [amount_label] | <code>string</code> | Label shown next to the total amount to be paid. Required for [Stripe, ApplePay, GooglePay]. N/A for [FlyPay, Flypay V2, PayPal, Afterpay]. |
 | [country] | <code>string</code> | Country of the user. 2 letter ISO code format. Required for [Stripe, ApplePay, GooglePay, Afterpay]. N/A for [FlyPay, Flypay V2, PayPal]. |
 | [pay_later] | <code>boolean</code> | Used to enable Pay Later feature in PayPal Smart Checkout WalletButton integration when available. Optional for [PayPal]. N/A for other wallets. |
+| [hide_message] | <code>boolean</code> | Used to hide Pay Later message in PayPal Smart Checkout WalletButton integration. Optional for [PayPal]. N/A for other wallets. |
 | [standalone] | <code>boolean</code> | Used to enable Standalone Buttons feature in PayPal Smart Checkout WalletButton integration. Used together with `pay_later`. Optional for [PayPal]. N/A for other wallets. |
 | [show_billing_address] | <code>boolean</code> | Used to hide/show the billing address on ApplePay and GooglePay popups. Default value is false. Optional for [ApplePay, GooglePay]. N/A for other wallets. |
 | [request_payer_name] | <code>boolean</code> | Used mainly for fraud purposes - recommended set to true. Optional for [Stripe]. N/A for other wallets. |

package/docs/widget-examples.md

@@ -1,4 +1,5 @@
 ## Widget
+
 You can find description of all methods and parameters [here](https://www.npmjs.com/package/@paydock/client-sdk#widget-simple-example)
 
 A payment form where it is possible to enter card data/bank accounts and then receive a one-time
@@ -15,8 +16,8 @@ It is possible in real-time to monitor the actions of user with widget and get i
 
 You must create a container for the widget. Inside this tag, the widget will be initialized
 
-
 ### Initialization
+
 ```javascript
 var widget = new paydock.HtmlWidget('#widget', 'publicKey');
 widget.load();
@@ -33,7 +34,6 @@ widget.load();
 
 Then write only need 2 lines of code in js to initialize widget
 
-
 ### Full example
 
 ```html
@@ -59,19 +59,18 @@ Then write only need 2 lines of code in js to initialize widget
 </html>
 ```
 
-
 ## Widget advanced example
 
 ### Customization
 
 ```javascript
 widget.setStyles({
-		background_color: 'rgb(0, 0, 0)',
-		border_color: 'yellow',
-		text_color: '#FFFFAA',
-		button_color: 'rgba(255, 255, 255, 0.9)',
-		font_size: '20px'
-	});
+  background_color: 'rgb(0, 0, 0)',
+  border_color: 'yellow',
+  text_color: '#FFFFAA',
+  button_color: 'rgba(255, 255, 255, 0.9)',
+  font_size: '20px'
+ });
 ```
 
 This example shows how you can customize to your needs and design
@@ -80,9 +79,9 @@ This example shows how you can customize to your needs and design
 
 ```html
 <div id="widget"
-	 widget-style="text-color: #FFFFAA; border-color: #yellow"
-	 title="Payment form"
-	 finish-text="Payment resource was successfully accepted"></div>
+  widget-style="text-color: #FFFFAA; border-color: #yellow"
+  title="Payment form"
+  finish-text="Payment resource was successfully accepted"></div>
 ```
 
 This example shows how you can set style and texts from html
@@ -99,36 +98,174 @@ widget.setSupportedCardIcons(['mastercard', 'visa']); // add icons of supported
 
 This example shows how you can use a lot of other methods to settings your form
 
+### Error handling
+
+## Overview
+
+Error events are emitted when an error occurs during widget operations. These events provide detailed information about the error, including its category, cause, and contextual details.
+
+## Error Event Structure
+
+### Base Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `event` | `string` | Always set to `"error"` |
+| `purpose` | `string` | Indicates the purpose of the action that triggered the error event (e.g., `"payment_source"`) |
+| `message_source` | `string` | Source of the message (e.g., `"widget.paydock"`) |
+| `ref_id` | `string` | Reference ID for the operation |
+| `widget_id` | `string` | Unique identifier of the widget instance |
+| `error` | `object` | Error object containing error information |
+
+### Error Object Properties
+
+The `error` object contains detailed information about the error:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `category` | `string` | High-level error classification |
+| `cause` | `string` | Specific error cause |
+| `retryable` | `boolean` | Indicates if the operation can be retried |
+| `details` | `object` | Additional error context |
+
+## Error Categories
+
+| Category | Description |
+|----------|-------------|
+| `configuration` | Configuration-related errors |
+| `identity_access_management` | Authentication and authorization errors |
+| `internal` | Internal system errors |
+| `process` | Process and operation errors |
+| `resource` | Resource-related errors |
+| `validation` | Input validation errors |
+
+## Error Causes
+
+| Cause | Category | Description |
+|-------|----------|-------------|
+| `aborted` | `process` | Operation was aborted |
+| `access_forbidden` | `identity` | Access to resource is forbidden |
+| `already_exists` | `validation` | Resource already exists |
+| `canceled` | `process` | Operation was canceled |
+| `invalid_configuration` | `configuration` | Invalid widget configuration |
+| `invalid_input` | `validation` | Invalid input provided |
+| `not_found` | `resource` | Requested resource not found |
+| `not_implemented` | `process` | Requested feature not implemented |
+| `rate_limited` | `process` | Too many requests |
+| `server_busy` | `process` | Server is too busy to handle request |
+| `service_unreachable` | `process` | Unable to reach required service |
+| `unauthorized` | `identity` | Authentication required |
+| `unknown_error` | `internal` | Unexpected error occurred |
+| `unprocessable_entity` | `validation` | Valid input but cannot be processed |
+
+## Error Details Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cause` | `string` | Matches the top-level error cause |
+| `contextId` | `string` | Context identifier (usually matches widget_id) |
+| `message` | `string` | Human-readable error message |
+| `timestamp` | `string` | ISO 8601 timestamp of when the error occurred |
+
+## Example
+
+```javascript
+widget.hideUiErrors(); // hide default UI errors and handle errors by listening to error events with widget.on('error')
+
+widget.on('error', (error) => {
+    console.log(error);
+    // {
+    //     "event": "error",
+    //     "purpose": "payment_source",
+    //     "message_source": "widget.paydock",
+    //     "ref_id": "",
+    //     "widget_id": "d4744f30-dcf5-168e-7f78-c8273a3401d4",
+    //     "error": {
+    //         "category": "process",
+    //         "cause": "service_unreachable",
+    //         "details": {
+    //             "cause": "service_unreachable",
+    //             "contextId": "d4744f30-dcf5-168e-7f78-c8273a3401d4",
+    //             "message": "The service is not availabe",
+    //             "timestamp": "2025-02-13T09:30:21.157Z"
+    //         },
+    //         "retryable": false
+    //     }
+    // }
+});
+```
+
+## Handling Errors (Tips)
+
+When handling errors, consider:
+
+1. Check the `retryable` flag to determine if the operation can be retried
+2. Use the `category` for high-level error handling logic
+3. Use the `cause` for specific error handling cases
+4. The `contextId` can be used for error tracking and debugging
+5. The `timestamp` helps with error logging and debugging
+
 ### Full example
 
 ```html
 <!DOCTYPE html>
 <html lang="en">
 <head>
-	<meta charset="UTF-8">
-	<title>Title</title>
-	<style>iframe {border: 0;width: 100%;height: 400px;}</style>
+ <meta charset="UTF-8">
+ <title>Title</title>
+ <style>iframe {border: 0;width: 100%;height: 400px;}</style>
 </head>
 <body>
 <form id="paymentForm">
     <div id="widget"
         widget-style="text-color: #FFFFAA; border-color: #yellow"
         title="Payment form"
-        finish-text="Payment resource was successfully accepted"></div>
+        finish-text="Payment resource was successfully accepted">
+    </div>
+
+    <div 
+        id="error" 
+        style="
+            display: none;
+            max-width: 600px;
+            margin: 16px auto;
+            padding: 16px 20px;
+            border-radius: 8px;
+            background-color: #FEF2F2;
+            border: 1px solid #FEE2E2;
+            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+            font-family: system-ui, -apple-system, sans-serif;
+            color: #991B1B;
+            line-height: 1.5;
+            font-size: 14px;
+        "
+        title="error"
+        >
+        <div style="display: flex; align-items: flex-start; gap: 12px;">
+            <div>
+                <h4 style="margin: 0 0 4px 0; font-size: 14px; font-weight: 600;">Access Error</h4>
+                <div id="error-message"></div>
+            </div>
+        </div>
+    </div> 
 </form>
 
 <script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
 <script>
-	var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
-
-	widget.setSupportedCardIcons(['mastercard', 'visa']);
-	widget.setFormFields(['phone', 'email']);
-	widget.setRefId('custom-ref-id');
-    widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');z
-
-	widget.load();
-</script>
+ var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
+
+ widget.setSupportedCardIcons(['mastercard', 'visa']);
+ widget.setFormFields(['phone', 'email']);
+ widget.setRefId('custom-ref-id');
+    widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
+
+    widget.on('error', ({ error }) => {
+        document.getElementById('error-message').textContent = error.details.message;
+        document.getElementById('error').style.display = 'block';
+    });
+ widget.load();
 </script>
+
 </body>
 </html>
 ```

package/examples/multi-html-widget/extend.html

@@ -24,6 +24,11 @@
 		new paydock.Configuration('gatewayId', 'bank_account')
 	]);
 
+	// ### listen to access errors and handle them ###
+	widget.on('error', function (error) {
+		console.error('An error occurred', error);
+	});
+
 	widget.load();
 </script>
 </body>

package/package.json

@@ -104,7 +104,7 @@
     }
   },
   "name": "@paydock/client-sdk",
-  "version": "1.113.2",
+  "version": "1.114.7-beta",
   "scripts": {
     "build:doc": "node docs/html/marked.js",
     "build:js": "rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
@@ -151,7 +151,7 @@
     "@babel/preset-env": "7.24.5",
     "@babel/runtime": "7.24.5",
     "@babel/runtime-corejs2": "7.24.5",
-    "@biomejs/biome": "1.7.3",
+    "@biomejs/biome": "1.9.4",
     "@rollup/plugin-babel": "6.0.4",
     "@rollup/plugin-commonjs": "25.0.7",
     "@rollup/plugin-json": "6.1.0",