@paydock/client-sdk 1.120.1-beta → 1.121.0

package/README.md

@@ -99,6 +99,7 @@ format that can be used in RequireJS, Webpack, etc.
 
 
 ## 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
@@ -115,8 +116,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();
@@ -133,7 +134,6 @@ widget.load();
 
 Then write only need 2 lines of code in js to initialize widget
 
-
 ### Full example
 
 ```html
@@ -159,19 +159,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
@@ -180,9 +179,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
@@ -199,19 +198,112 @@ 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) => {
-    const errorDiv = document.getElementById('error');
-    const errorMessage = document.getElementById('error-message');
-    
-    errorMessage.textContent = error.data.message;
-    errorDiv.style.display = 'block';
+    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
 
@@ -219,9 +311,9 @@ widget.on('error', (error) => {
 <!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">
@@ -260,18 +352,18 @@ widget.on('error', (error) => {
 
 <script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
 <script>
-	var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
+ var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
 
-	widget.setSupportedCardIcons(['mastercard', 'visa']);
-	widget.setFormFields(['phone', 'email']);
-	widget.setRefId('custom-ref-id');
+ 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.data.message;
+    widget.on('error', ({ error }) => {
+        document.getElementById('error-message').textContent = error.details.message;
         document.getElementById('error').style.display = 'block';
     });
-	widget.load();
+ widget.load();
 </script>
 
 </body>
@@ -706,6 +798,7 @@ Class Widget include method for working on html and include extended by HtmlMult
     * [.setRefId(refId)](#user-content-w_MultiWidget+setRefId)
     * [.useGatewayFieldValidation()](#user-content-w_MultiWidget+useGatewayFieldValidation)
     * [.setSupportedCardIcons(elements, validateCardNumberInput)](#user-content-w_MultiWidget+setSupportedCardIcons)
+    * [.hideUiErrors()](#user-content-w_MultiWidget+hideUiErrors)
     * [.setEnv(env, [alias])](#user-content-w_MultiWidget+setEnv)
     * [.loadIFrameUrl()](#user-content-w_MultiWidget+loadIFrameUrl)
     * [.setLanguage(code)](#user-content-w_MultiWidget+setLanguage)
@@ -1337,6 +1430,18 @@ Current method can set icons of supported card types
 ```javascript
 widget.setSupportedCardIcons(['mastercard', 'visa'], validateCardNumberInput);
 ```
+<a name="w_MultiWidget+hideUiErrors" id="w_MultiWidget+hideUiErrors" href="#user-content-w_MultiWidget+hideUiErrors">&nbsp;</a>
+
+### htmlWidget.hideUiErrors()
+Current method can hide prevent the widget from showing the error messages
+
+**Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
+**Overrides**: [<code>hideUiErrors</code>](#user-content-w_MultiWidget+hideUiErrors)  
+**Example**  
+
+```javascript
+widget.hideUiErrors('id');
+```
 <a name="w_MultiWidget+setEnv" id="w_MultiWidget+setEnv" href="#user-content-w_MultiWidget+setEnv">&nbsp;</a>
 
 ### htmlWidget.setEnv(env, [alias])
@@ -1431,6 +1536,7 @@ Class HtmlMultiWidget include method for working with html
     * [.setRefId(refId)](#user-content-w_MultiWidget+setRefId)
     * [.useGatewayFieldValidation()](#user-content-w_MultiWidget+useGatewayFieldValidation)
     * [.setSupportedCardIcons(elements, validateCardNumberInput)](#user-content-w_MultiWidget+setSupportedCardIcons)
+    * [.hideUiErrors()](#user-content-w_MultiWidget+hideUiErrors)
     * [.setEnv(env, [alias])](#user-content-w_MultiWidget+setEnv)
     * [.loadIFrameUrl()](#user-content-w_MultiWidget+loadIFrameUrl)
     * [.setLanguage(code)](#user-content-w_MultiWidget+setLanguage)
@@ -1963,6 +2069,18 @@ Current method can set icons of supported card types
 ```javascript
 widget.setSupportedCardIcons(['mastercard', 'visa'], validateCardNumberInput);
 ```
+<a name="w_MultiWidget+hideUiErrors" id="w_MultiWidget+hideUiErrors" href="#user-content-w_MultiWidget+hideUiErrors">&nbsp;</a>
+
+### htmlMultiWidget.hideUiErrors()
+Current method can hide prevent the widget from showing the error messages
+
+**Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
+**Overrides**: [<code>hideUiErrors</code>](#user-content-w_MultiWidget+hideUiErrors)  
+**Example**  
+
+```javascript
+widget.hideUiErrors('id');
+```
 <a name="w_MultiWidget+setEnv" id="w_MultiWidget+setEnv" href="#user-content-w_MultiWidget+setEnv">&nbsp;</a>
 
 ### htmlMultiWidget.setEnv(env, [alias])
@@ -2216,6 +2334,7 @@ Class MultiWidget include method for for creating iframe url
     * [.setRefId(refId)](#user-content-w_MultiWidget+setRefId)
     * [.useGatewayFieldValidation()](#user-content-w_MultiWidget+useGatewayFieldValidation)
     * [.setSupportedCardIcons(elements, validateCardNumberInput)](#user-content-w_MultiWidget+setSupportedCardIcons)
+    * [.hideUiErrors()](#user-content-w_MultiWidget+hideUiErrors)
     * [.setEnv(env, [alias])](#user-content-w_MultiWidget+setEnv)
     * [.loadIFrameUrl()](#user-content-w_MultiWidget+loadIFrameUrl)
     * [.setLanguage(code)](#user-content-w_MultiWidget+setLanguage)
@@ -2503,6 +2622,17 @@ Current method can set icons of supported card types
 ```javascript
 widget.setSupportedCardIcons(['mastercard', 'visa'], validateCardNumberInput);
 ```
+<a name="w_MultiWidget+hideUiErrors" id="w_MultiWidget+hideUiErrors" href="#user-content-w_MultiWidget+hideUiErrors">&nbsp;</a>
+
+### multiWidget.hideUiErrors()
+Current method can hide prevent the widget from showing the error messages
+
+**Kind**: instance method of [<code>MultiWidget</code>](#user-content-w_MultiWidget)  
+**Example**  
+
+```javascript
+widget.hideUiErrors('id');
+```
 <a name="w_MultiWidget+setEnv" id="w_MultiWidget+setEnv" href="#user-content-w_MultiWidget+setEnv">&nbsp;</a>
 
 ### multiWidget.setEnv(env, [alias])
@@ -5434,7 +5564,7 @@ button.onUpdate((data) => {
 After the payment is completed, the onPaymentSuccessful(data) will be called if the payment was successful. If the payment was not successful, the function onPaymentError(data) will be called. If fraud check is active for the gateway, a fraud body was sent in the wallet charge initialize call and the fraud service left the charge in review, then the onPaymentInReview(data) will be called.
 All three callbacks return relevant data according to each one of the scenarios.
 
-Note that these callbacks will not trigger for Afterpay wallet since the payment completion for it is done via Redirect method, and therefore this SDK won't be loaded once the payment is completed at checkout.
+>*Note that these callbacks will not be triggered for the Afterpay wallet when Redirect mode is used, that is when the charge is initialized with the success_url and error_url parameters, since the payment completion is done through the Redirect method, and therefore this SDK will not be loaded once the payment is completed at checkout.*
 
 ```javascript
 button.onPaymentSuccessful((data) => console.log("The payment was successful"));
@@ -5636,7 +5766,7 @@ _(Required `meta` fields: - . Optional `meta` fields: -)_
 
 This example shows how to use these functions for **ApplePay via MPGS** and **GooglePay via MPGS**:
 
-_(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `raw_data_initialization`, `request_shipping`, `style.button_type`)_
+_(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `raw_data_initialization`, `request_shipping`, `style.button_type`, `style.button_style`)_
 ### ApplePay and GooglePay via MPGS Full example
 
 ```html
@@ -5668,6 +5798,7 @@ _(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `ra
                 },
                 apple: {
                     button_type: 'buy',
+                    button_style: 'black',
                 },
             },
             shipping_options: [
@@ -5784,6 +5915,7 @@ Similarly, for **GooglePay via MPGS** you can initialize the `PaymentMethodSpeci
                 },
                 apple: {
                     button_type: 'buy',
+                    button_style: 'black',
                 },
             },
             shipping_options: [
@@ -6007,10 +6139,12 @@ Interface of data used by the wallet checkout and payment proccess.
 | [merchant_name] | <code>string</code> | Merchant Name used for GooglePay integration via MPGS. Required for [GooglePay]. N/A for other wallets. |
 | [raw_data_initialization] | <code>object</code> | Used to provide values to initialize wallet with raw data. Optional for [ApplePay]. N/A for the other wallets. |
 | [style] | <code>object</code> | For **Paypal**: used to style the buttons, check possible values in the [style guide](https://developer.paypal.com/docs/business/checkout/reference/style-guide). When `standalone` and `pay_later`, extra options can be provided in `style.messages` with the [messages style options](https://developer.paypal.com/docs/checkout/pay-later/us/integrate/reference/#stylelayout). Also used at **ApplePay**, **GooglePay** and **Afterpay** to select button type. Optional for [PayPal, ApplePay, GooglePay, Afterpay]. N/A for [Stripe, FlyPay, Flypay V2]. |
-| [style.button_type] | <code>object</code> | Used to select ApplePay button type (e.g: 'buy','donate', etc), check possible values at https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons_using_css. Also select button type for GooglePay (check GooglePayStyles) and Afterpay (check AfterpayStyles). Optional for [ApplePay, GooglePay, Afterpay]. N/A for other wallets. |
+| [style.button_type] | <code>object</code> | Used to select ApplePay button type (e.g: 'buy','donate', etc), check possible values [here](https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons_using_css). Also select button type for GooglePay (check GooglePayStyles) and Afterpay (check AfterpayStyles). Optional for [ApplePay, GooglePay, Afterpay]. N/A for other wallets. |
+| [style.button_style] | <code>object</code> | Used to select ApplePay button style (e.g: 'black', 'white', etc), check possible values [here](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaybuttonstyle). Optional for [ApplePay]. N/A for other wallets. |
 | [style.height] | <code>object</code> | Used to select Afterpay button height. Optional for [Afterpay]. N/A for other wallets. |
 | [wallets] | <code>array</code> | By default if this is not sent or empty, we will try to show either Apple Pay or Google Pay buttons. This can be limited sending the following array in this field: ['apple','google]. Optional for [Stripe, ApplePay, GooglePay]. N/A for other wallets. |
 | [client_id] | <code>string</code> | Client ID to be used in the provider system. Required for [Flypay V2]. N/A for [FlyPay, GooglePay, ApplePay, PayPal, Afterpay]. |
+| [apple_pay_capabilities] | <code>Array.&lt;(&#x27;credentials\_available&#x27;\|&#x27;credentials\_status\_unknown&#x27;\|&#x27;credentials\_unavailable&#x27;)&gt;</code> | Device capabilities needed for wallet button to be available. For further information about refer to [the documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/4440085-applepaycapabilities). If the recognized value is credentials_status_unknown, the payment most possibly cannot be finished on the web, and the buyer must complete it on a compatible device, like Iphone, via QR scan. Optional parameter for [ApplePay]. N/A for [FlyPay, GooglePay, Flypay V2, PayPal, Afterpay]. |
 
 <a name="IApplePayShippingOption" id="IApplePayShippingOption" href="#IApplePayShippingOption">&nbsp;</a>
 
@@ -6710,7 +6844,10 @@ A full description of the meta parameters for [PaypalWalletButtonExpress](#Paypa
 
 <dl>
 <dt><a href="#ApplePayWalletMeta">ApplePayWalletMeta</a> : <code>object</code></dt>
-<dd><p>Interface for configuration metadata specific to ApplePay integration in the wallet checkout and payment process.</p>
+<dd><p>Interface for configuration metadata specific to ApplePay integration in the wallet checkout and payment process.
+For further information about ApplePay Capabilities refer to <a href="https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/4440085-applepaycapabilities">the documentation</a>.
+Apple will determinate if the device has an ApplePay wallet available and at least one active payment.
+If the determinated value is credentials_status_unknown, the payment possbily should might be not able to be finished on the web, and the buyer must complete it on a compatible device, like Iphone or Ipad.</p>
 </dd>
 <dt><a href="#PaypalWalletMeta">PaypalWalletMeta</a> : <code>object</code></dt>
 <dd><p>Interface for configuration metadata specific to PayPal integration in the wallet checkout and payment process.
@@ -6743,6 +6880,9 @@ For in-depth information, please refer to the <a href="https://developer.paypal.
 
 ## ApplePayWalletMeta : <code>object</code>
 Interface for configuration metadata specific to ApplePay integration in the wallet checkout and payment process.
+For further information about ApplePay Capabilities refer to [the documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/4440085-applepaycapabilities).
+Apple will determinate if the device has an ApplePay wallet available and at least one active payment.
+If the determinated value is credentials_status_unknown, the payment possbily should might be not able to be finished on the web, and the buyer must complete it on a compatible device, like Iphone or Ipad.
 
 **Kind**: global interface  
 
@@ -6760,6 +6900,7 @@ Interface for configuration metadata specific to ApplePay integration in the wal
 | [style] | <code>object</code> | Styling configuration for ApplePay buttons displayed during checkout. |
 | [style.button_type] | <code>ApplePayButtonType</code> | Enum type to select the type of ApplePay button (e.g., 'buy', 'donate', etc.), providing user interface customization. |
 | [style.button_style] | <code>ApplePayButtonStyle</code> | Style applied to the ApplePay button, which can include color and form factor adjustments according to the brand's visual guidelines. |
+| [apple_pay_capabilities] | <code>Array.&lt;(&#x27;credentials\_available&#x27;\|&#x27;credentials\_status\_unknown&#x27;\|&#x27;credentials\_unavailable&#x27;)&gt;</code> | Device capabilities needed for wallet button to be available. |
 
 <a name="PaypalWalletMeta" id="PaypalWalletMeta" href="#PaypalWalletMeta">&nbsp;</a>