@paydock/client-sdk 1.120.1 → 1.122.2-beta

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>
 
@@ -6678,6 +6812,9 @@ A full description of the meta parameters for [PaypalWalletButtonExpress](#Paypa
 <dt><a href="#EVENT">EVENT</a> : <code>object</code></dt>
 <dd><p>List of available event&#39;s name in the wallet button lifecycle</p>
 </dd>
+<dt><a href="#ContactFieldType">ContactFieldType</a> : <code>object</code></dt>
+<dd><p>List of available contact fields for ContactFieldType</p>
+</dd>
 </dl>
 
 ## Typedefs
@@ -6698,6 +6835,12 @@ A full description of the meta parameters for [PaypalWalletButtonExpress](#Paypa
 <dt><a href="#OnCheckoutCloseCallback">OnCheckoutCloseCallback</a> : <code>function</code></dt>
 <dd><p>Callback for onCheckoutClose method.</p>
 </dd>
+<dt><a href="#OnShippingAddressChangeCallback">OnShippingAddressChangeCallback</a> ⇒ <code><a href="#OnShippingAddressChangeEventResponse">Promise.&lt;OnShippingAddressChangeEventResponse&gt;</a></code></dt>
+<dd><p>Callback for onShippingAddressChange method.</p>
+</dd>
+<dt><a href="#OnShippingOptionsChangeCallback">OnShippingOptionsChangeCallback</a> ⇒ <code><a href="#OnShippingOptionChangeEventResponse">Promise.&lt;OnShippingOptionChangeEventResponse&gt;</a></code></dt>
+<dd><p>Callback for onShippingOptionsChange method.</p>
+</dd>
 <dt><a href="#OnUnavailableCallback">OnUnavailableCallback</a> : <code>function</code></dt>
 <dd><p>Callback for onUnavailable method.</p>
 </dd>
@@ -6710,7 +6853,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.
@@ -6737,12 +6883,34 @@ For in-depth information, please refer to the <a href="https://developer.paypal.
 <dt><a href="#OnErrorEventData">OnErrorEventData</a> : <code>object</code></dt>
 <dd><p>Interface for OnErrorEventData</p>
 </dd>
+<dt><a href="#OnShippingAddressChangeEventData">OnShippingAddressChangeEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnShippingAddressChangeEventData.</p>
+</dd>
+<dt><a href="#OnShippingAddressChangeEventResponse">OnShippingAddressChangeEventResponse</a> : <code>object</code></dt>
+<dd><p>Interface for OnShippingAddressChangeEventResponse.</p>
+</dd>
+<dt><a href="#IApplePayShippingOption">IApplePayShippingOption</a> : <code>object</code></dt>
+<dd><p>Interface for IApplePayShippingOption.
+Used for adding new shippings options when customer updates the shipping address.</p>
+</dd>
+<dt><a href="#OnShippingOptionChangeEventData">OnShippingOptionChangeEventData</a> : <code>object</code></dt>
+<dd><p>Interface for OnShippingOptionChangeEventData.</p>
+</dd>
+<dt><a href="#OnShippingOptionChangeEventResponse">OnShippingOptionChangeEventResponse</a> : <code>object</code></dt>
+<dd><p>Interface for OnShippingOptionChangeEventResponse.</p>
+</dd>
+<dt><a href="#IApplePayError">IApplePayError</a> : <code>object</code></dt>
+<dd><p>Interface for IApplePayError.</p>
+</dd>
 </dl>
 
 <a name="ApplePayWalletMeta" id="ApplePayWalletMeta" href="#ApplePayWalletMeta">&nbsp;</a>
 
 ## 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  
 
@@ -6755,11 +6923,15 @@ Interface for configuration metadata specific to ApplePay integration in the wal
 | [merchant_capabilities] | <code>Array.&lt;(&#x27;supports3DS&#x27;\|&#x27;supportsEMV&#x27;\|&#x27;supportsCredit&#x27;\|&#x27;supportsDebit&#x27;)&gt;</code> | Array of capabilities that the merchant supports, influencing the transaction processing features available. |
 | [supported_networks] | <code>Array.&lt;(&#x27;visa&#x27;\|&#x27;masterCard&#x27;\|&#x27;amex&#x27;\|&#x27;chinaUnionPay&#x27;\|&#x27;discover&#x27;\|&#x27;interac&#x27;\|&#x27;jcb&#x27;\|&#x27;privateLabel&#x27;)&gt;</code> | List of payment networks supported by the merchant for ApplePay transactions. |
 | [required_billing_contact_fields] | <code>Array.&lt;(&#x27;email&#x27;\|&#x27;name&#x27;\|&#x27;phone&#x27;\|&#x27;postalAddress&#x27;)&gt;</code> | Contact fields required from the user for billing purposes, improving transaction verification and fraud prevention. Phone and email are currently not returned by Apple. |
-| [required_shipping_contact_fields] | <code>Array.&lt;(&#x27;email&#x27;\|&#x27;phone&#x27;)&gt;</code> | Shipping contact fields that are mandatory to complete the transaction. Use email and phone to collect from customer wallet in the abscense of billing one. |
+| [required_shipping_contact_fields] | <code>Array.&lt;(&#x27;email&#x27;\|&#x27;phone&#x27;)&gt;</code> | Shipping contact fields that are mandatory to complete the transaction. Use email and phone to collect from customer wallet in the abscense of billing one. Required for onShippingAddressChange callback. |
 | [supported_countries] | <code>Array.&lt;string&gt;</code> | List of countries where ApplePay is supported by the merchant, restricting usage to specified regions. |
 | [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. |
+| [shipping_editing_mode] | <code>&#x27;available&#x27;</code> \| <code>&#x27;store\_pickup&#x27;</code> | ApplePay - available for allowing editing shipping, store_pickup for not allowing editing shipping. |
+| [shipping_data] | <code>object</code> | ApplePay - Preloaded data used for populate shipping address information |
+| [shipping_data.email_address] | <code>string</code> | ApplePay - The shipping address email |
+| [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>
 
@@ -6891,6 +7063,115 @@ Interface for OnErrorEventData
 | [chargeId] | <code>string</code> | chargeId in case it's already set after onClick event |
 | [data] | <code>Error</code> | Error object if present |
 
+<a name="OnShippingAddressChangeEventData" id="OnShippingAddressChangeEventData" href="#OnShippingAddressChangeEventData">&nbsp;</a>
+
+## OnShippingAddressChangeEventData : <code>object</code>
+Interface for OnShippingAddressChangeEventData.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Event Name is 'onShippingAddressChange' |
+| chargeId | <code>string</code> | chargeId set after onClick event |
+| data.address_city | <code>string</code> | PayPal and ApplePay - Shipping address city |
+| data.address_state | <code>string</code> | PayPal and ApplePay - Shipping address state |
+| data.address_postcode | <code>string</code> | PayPal and ApplePay - Shipping address postcode |
+| data.address_country | <code>string</code> | PayPal and ApplePay - Shipping address country code |
+| [data.address_line1] | <code>string</code> | ApplePay - Shipping address line 1 |
+| [data.address_line2] | <code>string</code> | ApplePay - Shipping address line 2 |
+| [data.contact.phone] | <code>string</code> | ApplePay - Shipping contact phone |
+| [data.contact.email] | <code>string</code> | ApplePay - Shipping contact email |
+| [data.contact.first_name] | <code>string</code> | ApplePay - Shipping contact first name |
+| [data.contact.last_name] | <code>string</code> | ApplePay - Shipping contact last name |
+
+<a name="OnShippingAddressChangeEventResponse" id="OnShippingAddressChangeEventResponse" href="#OnShippingAddressChangeEventResponse">&nbsp;</a>
+
+## OnShippingAddressChangeEventResponse : <code>object</code>
+Interface for OnShippingAddressChangeEventResponse.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [token] | <code>string</code> | Updated Wallet Token if any |
+| [label] | <code>string</code> | ApplePay - Required. Label to show to the customer. |
+| [amount] | <code>string</code> | ApplePay - Required. New amount for shipping option. |
+| [error] | <code>string</code> | PayPal and ApplePay - Error object in case of error when processing shipping address in if new address unsupported or any other possible error. |
+| error.code | <code>string</code> | PayPal and ApplePay - Error code, mandatory in case of error. Possible values for Paypal are 'address_error', 'country_error', 'state_error', 'zip_error' or any other string if none applies. For ApplePay values are 'address_error', 'shipping_contact_invalid' and 'billing_contact_invalid'. |
+| [error.field] | <code>string</code> | ApplePay - Error field in case of specifically showing it. Possible values for Apple Pay are 'phone', 'email', 'name', 'phonetic_name', 'address_lines', 'locality', 'postal_code', 'administrative_area', 'country', 'country_code'. |
+| [error.message] | <code>string</code> | ApplePay - Custom user facing error message. |
+
+<a name="IApplePayShippingOption" id="IApplePayShippingOption" href="#IApplePayShippingOption">&nbsp;</a>
+
+## IApplePayShippingOption : <code>object</code>
+Interface for IApplePayShippingOption.
+Used for adding new shippings options when customer updates the shipping address.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [id] | <code>string</code> | Updated Wallet Token if any |
+| [label] | <code>string</code> | ApplePay - Required. Label to show to the customer. |
+| [amount] | <code>string</code> | ApplePay - Required. New amount for shipping option. |
+| [detail] | <code>string</code> | ApplePay - Optional detail for shipping option. |
+| [date_components_range] | <code>object</code> | ApplePay - Object that contains the dates for shipping |
+| [date_components_range.start_date_components] | <code>object</code> | ApplePay - Contains the start date object |
+| [date_components_range.start_date_components.years] | <code>string</code> | ApplePay - Contains the start date year |
+| [date_components_range.start_date_components.months] | <code>string</code> | ApplePay - Contains the start date month |
+| [date_components_range.start_date_components.days] | <code>string</code> | ApplePay - Contains the start date day |
+| [date_components_range.start_date_components.hours] | <code>string</code> | ApplePay - Contains the start date hour |
+| [date_components_range.end_date_components] | <code>object</code> | ApplePay - Contains the end date year |
+| [date_components_range.end_date_components.years] | <code>string</code> | ApplePay - Contains the end date year |
+| [date_components_range.end_date_components.months] | <code>string</code> | ApplePay - Contains the end date month |
+| [date_components_range.end_date_components.days] | <code>string</code> | ApplePay - Contains the end date day |
+| [date_components_range.end_date_components.hours] | <code>string</code> | ApplePay - Contains the end date hour |
+
+<a name="OnShippingOptionChangeEventData" id="OnShippingOptionChangeEventData" href="#OnShippingOptionChangeEventData">&nbsp;</a>
+
+## OnShippingOptionChangeEventData : <code>object</code>
+Interface for OnShippingOptionChangeEventData.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>string</code> | Event Name is 'onShippingOptionsChange' |
+| chargeId | <code>string</code> | chargeId set after onClick event |
+| [data.shipping_option_id] | <code>string</code> | PayPal and ApplePay - Selected shipping option id |
+| [data.amount] | <code>string</code> | Paypal and ApplePay - Selected shipping option amount |
+| [data.label] | <code>string</code> | ApplePay - Selected shipping option label |
+| [data.detail] | <code>string</code> | ApplePay - Selected shipping option detail |
+
+<a name="OnShippingOptionChangeEventResponse" id="OnShippingOptionChangeEventResponse" href="#OnShippingOptionChangeEventResponse">&nbsp;</a>
+
+## OnShippingOptionChangeEventResponse : <code>object</code>
+Interface for OnShippingOptionChangeEventResponse.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [token] | <code>string</code> | Updated Wallet Token if any |
+| [label] | <code>string</code> | ApplePay - Required. Label to show to the customer. |
+| [amount] | <code>string</code> | ApplePay - Required. New amount for shipping option. |
+| [error] | <code>string</code> | PayPal - Error object in case of error when processing shipping option selection. |
+| error.code | <code>string</code> | Possible values for Paypal are 'method_unavailable', 'store_unavailable' or any other string if none applies. |
+
+<a name="IApplePayError" id="IApplePayError" href="#IApplePayError">&nbsp;</a>
+
+## IApplePayError : <code>object</code>
+Interface for IApplePayError.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| code | <code>&#x27;shipping\_contact\_invalid&#x27;</code> \| <code>&#x27;billing\_contact\_invalid&#x27;</code> \| <code>&#x27;address\_unserviceable&#x27;</code> \| <code>&#x27;coupon\_code\_invalid&#x27;</code> \| <code>&#x27;coupon\_code\_expired&#x27;</code> \| <code>&#x27;unknown&#x27;</code> | The error code for this instance. |
+| contact_field | [<code>ContactFieldType</code>](#ContactFieldType) | The error code for this instance. |
+| message | <code>string</code> \| <code>undefined</code> | TA localized, user-facing string that describes the error. |
+
 <a name="ApplePayWalletButtonExpress" id="ApplePayWalletButtonExpress" href="#ApplePayWalletButtonExpress">&nbsp;</a>
 
 ## ApplePayWalletButtonExpress ⇐ <code>BaseWalletButton</code>
@@ -6909,6 +7190,8 @@ Class ApplePayWalletButtonExpress to work with Apple Pay Wallet.
     * [.onPaymentInReview([handler])](#BaseWalletButton+onPaymentInReview)
     * [.onPaymentError([handler])](#BaseWalletButton+onPaymentError)
     * [.onCheckoutClose(handler)](#BaseWalletButton+onCheckoutClose)
+    * [.onShippingAddressChange([handler])](#BaseWalletButton+onShippingAddressChange)
+    * [.onShippingOptionsChange([handler])](#BaseWalletButton+onShippingOptionsChange)
     * [.onUnavailable(handler)](#BaseWalletButton+onUnavailable)
     * [.onError(handler)](#BaseWalletButton+onError)
 
@@ -7085,6 +7368,52 @@ button.onCheckoutClose(() => {
      console.log('Wallet checkout closes');
 });
 ```
+<a name="BaseWalletButton+onShippingAddressChange" id="BaseWalletButton+onShippingAddressChange" href="#BaseWalletButton+onShippingAddressChange">&nbsp;</a>
+
+### applePayWalletButtonExpress.onShippingAddressChange([handler])
+If shipping address data is updated, the function passed as parameter will be called.
+Use this method to listen for shipping address selection or input from customer when shipping is enabled.
+The event handler needs to return a new token in case a backend to backend wallet update call was executed.
+In addition, if any error occured, an error string must be supplied.
+By default, the event handler will be processed successfuly if neither token nor error is returned.
+
+**Kind**: instance method of [<code>ApplePayWalletButtonExpress</code>](#ApplePayWalletButtonExpress)  
+**Overrides**: [<code>onShippingAddressChange</code>](#BaseWalletButton+onShippingAddressChange)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | [<code>OnShippingAddressChangeCallback</code>](#OnShippingAddressChangeCallback) | Function to be called when the shipping address data is updated. |
+
+**Example**  
+```js
+button.onShippingAddressChange((data) => {
+    const responseData = await fetch('https://your-server.com/update-shipping-info');
+    return { error: null, token: responseData.walletToken };
+});
+```
+<a name="BaseWalletButton+onShippingOptionsChange" id="BaseWalletButton+onShippingOptionsChange" href="#BaseWalletButton+onShippingOptionsChange">&nbsp;</a>
+
+### applePayWalletButtonExpress.onShippingOptionsChange([handler])
+If shipping options data is updated, the function passed as parameter will be called.
+Use this method to listen for shipping option selection from customer when shipping is enabled.
+The event handler needs to return a new token in case a backend to backend wallet update call was executed.
+In addition, if any error occured, an error string must be supplied.
+By default, the event handler will be processed successfuly if neither token nor error is returned.
+
+**Kind**: instance method of [<code>ApplePayWalletButtonExpress</code>](#ApplePayWalletButtonExpress)  
+**Overrides**: [<code>onShippingOptionsChange</code>](#BaseWalletButton+onShippingOptionsChange)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | [<code>OnShippingOptionsChangeCallback</code>](#OnShippingOptionsChangeCallback) | Function to be called when the shipping options data is updated. |
+
+**Example**  
+```js
+button.onShippingOptionsChange((data) => {
+    const responseData = await fetch('https://your-server.com/update-shipping-info');
+    return { error: null, token: responseData.walletToken };
+});
+```
 <a name="BaseWalletButton+onUnavailable" id="BaseWalletButton+onUnavailable" href="#BaseWalletButton+onUnavailable">&nbsp;</a>
 
 ### applePayWalletButtonExpress.onUnavailable(handler)
@@ -7140,6 +7469,8 @@ Class PaypalWalletButtonExpress to work with Paypal Wallet.
     * [.onPaymentInReview([handler])](#BaseWalletButton+onPaymentInReview)
     * [.onPaymentError([handler])](#BaseWalletButton+onPaymentError)
     * [.onCheckoutClose(handler)](#BaseWalletButton+onCheckoutClose)
+    * [.onShippingAddressChange([handler])](#BaseWalletButton+onShippingAddressChange)
+    * [.onShippingOptionsChange([handler])](#BaseWalletButton+onShippingOptionsChange)
     * [.onUnavailable(handler)](#BaseWalletButton+onUnavailable)
     * [.onError(handler)](#BaseWalletButton+onError)
 
@@ -7316,6 +7647,52 @@ button.onCheckoutClose(() => {
      console.log('Wallet checkout closes');
 });
 ```
+<a name="BaseWalletButton+onShippingAddressChange" id="BaseWalletButton+onShippingAddressChange" href="#BaseWalletButton+onShippingAddressChange">&nbsp;</a>
+
+### paypalWalletButtonExpress.onShippingAddressChange([handler])
+If shipping address data is updated, the function passed as parameter will be called.
+Use this method to listen for shipping address selection or input from customer when shipping is enabled.
+The event handler needs to return a new token in case a backend to backend wallet update call was executed.
+In addition, if any error occured, an error string must be supplied.
+By default, the event handler will be processed successfuly if neither token nor error is returned.
+
+**Kind**: instance method of [<code>PaypalWalletButtonExpress</code>](#PaypalWalletButtonExpress)  
+**Overrides**: [<code>onShippingAddressChange</code>](#BaseWalletButton+onShippingAddressChange)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | [<code>OnShippingAddressChangeCallback</code>](#OnShippingAddressChangeCallback) | Function to be called when the shipping address data is updated. |
+
+**Example**  
+```js
+button.onShippingAddressChange((data) => {
+    const responseData = await fetch('https://your-server.com/update-shipping-info');
+    return { error: null, token: responseData.walletToken };
+});
+```
+<a name="BaseWalletButton+onShippingOptionsChange" id="BaseWalletButton+onShippingOptionsChange" href="#BaseWalletButton+onShippingOptionsChange">&nbsp;</a>
+
+### paypalWalletButtonExpress.onShippingOptionsChange([handler])
+If shipping options data is updated, the function passed as parameter will be called.
+Use this method to listen for shipping option selection from customer when shipping is enabled.
+The event handler needs to return a new token in case a backend to backend wallet update call was executed.
+In addition, if any error occured, an error string must be supplied.
+By default, the event handler will be processed successfuly if neither token nor error is returned.
+
+**Kind**: instance method of [<code>PaypalWalletButtonExpress</code>](#PaypalWalletButtonExpress)  
+**Overrides**: [<code>onShippingOptionsChange</code>](#BaseWalletButton+onShippingOptionsChange)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | [<code>OnShippingOptionsChangeCallback</code>](#OnShippingOptionsChangeCallback) | Function to be called when the shipping options data is updated. |
+
+**Example**  
+```js
+button.onShippingOptionsChange((data) => {
+    const responseData = await fetch('https://your-server.com/update-shipping-info');
+    return { error: null, token: responseData.walletToken };
+});
+```
 <a name="BaseWalletButton+onUnavailable" id="BaseWalletButton+onUnavailable" href="#BaseWalletButton+onUnavailable">&nbsp;</a>
 
 ### paypalWalletButtonExpress.onUnavailable(handler)
@@ -7369,6 +7746,28 @@ List of available event's name in the wallet button lifecycle
 | PAYMENT_IN_REVIEW | <code>string</code> | <code>&quot;paymentInReview&quot;</code> | 
 | ON_CLICK | <code>string</code> | <code>&quot;onClick&quot;</code> | 
 | ON_CHECKOUT_CLOSE | <code>string</code> | <code>&quot;onCheckoutClose&quot;</code> | 
+| ON_SHIPPING_ADDRESS_CHANGE | <code>string</code> | <code>&quot;onShippingAddressChange&quot;</code> | 
+| ON_SHIPPING_OPTIONS_CHANGE | <code>string</code> | <code>&quot;onShippingOptionsChange&quot;</code> | 
+
+<a name="ContactFieldType" id="ContactFieldType" href="#ContactFieldType">&nbsp;</a>
+
+## ContactFieldType : <code>object</code>
+List of available contact fields for ContactFieldType
+
+**Kind**: global constant  
+
+| Param | Type |
+| --- | --- |
+| phone | <code>string</code> | 
+| email | <code>string</code> | 
+| name | <code>string</code> | 
+| phonetic_name | <code>string</code> | 
+| address_lines | <code>string</code> | 
+| address_city | <code>string</code> | 
+| address_postcode | <code>string</code> | 
+| address_state | <code>string</code> | 
+| address_country | <code>string</code> | 
+| address_country_code | <code>string</code> | 
 
 <a name="OnClickCallback" id="OnClickCallback" href="#OnClickCallback">&nbsp;</a>
 
@@ -7426,6 +7825,30 @@ Callback for onCheckoutClose method.
 | --- | --- |
 | data | [<code>OnCloseEventData</code>](#OnCloseEventData) | 
 
+<a name="OnShippingAddressChangeCallback" id="OnShippingAddressChangeCallback" href="#OnShippingAddressChangeCallback">&nbsp;</a>
+
+## OnShippingAddressChangeCallback ⇒ [<code>Promise.&lt;OnShippingAddressChangeEventResponse&gt;</code>](#OnShippingAddressChangeEventResponse)
+Callback for onShippingAddressChange method.
+
+**Kind**: global typedef  
+**Returns**: [<code>Promise.&lt;OnShippingAddressChangeEventResponse&gt;</code>](#OnShippingAddressChangeEventResponse) - Address update result  
+
+| Param | Type |
+| --- | --- |
+| data | [<code>OnShippingAddressChangeEventData</code>](#OnShippingAddressChangeEventData) | 
+
+<a name="OnShippingOptionsChangeCallback" id="OnShippingOptionsChangeCallback" href="#OnShippingOptionsChangeCallback">&nbsp;</a>
+
+## OnShippingOptionsChangeCallback ⇒ [<code>Promise.&lt;OnShippingOptionChangeEventResponse&gt;</code>](#OnShippingOptionChangeEventResponse)
+Callback for onShippingOptionsChange method.
+
+**Kind**: global typedef  
+**Returns**: [<code>Promise.&lt;OnShippingOptionChangeEventResponse&gt;</code>](#OnShippingOptionChangeEventResponse) - Address update result  
+
+| Param | Type |
+| --- | --- |
+| data | [<code>OnShippingOptionChangeEventData</code>](#OnShippingOptionChangeEventData) | 
+
 <a name="OnUnavailableCallback" id="OnUnavailableCallback" href="#OnUnavailableCallback">&nbsp;</a>
 
 ## OnUnavailableCallback : <code>function</code>