@paydock/client-sdk 1.104.3-beta → 1.104.7-beta

package/docs/api-widget.md

@@ -51,6 +51,12 @@
 <dt><a href="#user-content-w_STYLABLE_ELEMENT_STATE">STYLABLE_ELEMENT_STATE</a> : <code>object</code></dt>
 <dd><p>Current constant include available states of element for styling</p>
 </dd>
+<dt><a href="#user-content-w_CARD_VALIDATORS">CARD_VALIDATORS</a> : <code>Record.&lt;string, string&gt;</code></dt>
+<dd><p>List of available form field validators dedicated to cards and their definition</p>
+</dd>
+<dt><a href="#user-content-w_GENERIC_VALIDATORS">GENERIC_VALIDATORS</a> : <code>Record.&lt;string, string&gt;</code></dt>
+<dd><p>List of available generic form field validators and their definition</p>
+</dd>
 <dt><a href="#user-content-w_TRIGGER">TRIGGER</a> : <code>object</code></dt>
 <dd><p>List of available triggers</p>
 </dd>
@@ -63,7 +69,8 @@
 <dd><p>Interface of data from validation event.</p>
 </dd>
 <dt><a href="#user-content-w_IEventMetaData">IEventMetaData</a></dt>
-<dd><p>Interface of data from event.</p>
+<dd><p>Contains basic information associated with the event and additional meta data
+specific to the event. E.g., card info, gateway info, etc.</p>
 </dd>
 <dt><a href="#user-content-w_IEventAfterLoadData">IEventAfterLoadData</a></dt>
 <dd><p>Interface of data from event.</p>
@@ -112,33 +119,34 @@ Interface of data from validation event.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| event | <code>string</code> | Event name |
-| purpose | <code>string</code> | System variable. Purpose of event |
-| message_source | <code>string</code> | System variable. Event source |
-| [ref_id] | <code>string</code> | Custom value for identify result of processed operation |
-| [form_valid] | <code>boolean</code> | Form is valid |
-| [invalid_fields] | <code>array</code> | Invalid form fields |
-| [invalid_showed_fields] | <code>array</code> | List of fields on which the error is already displayed |
-| [validators] | <code>array</code> | List of validators with fields |
+| event | <code>string</code> | The name of the event. |
+| message_source | <code>string</code> | A system variable that identifies the event source. |
+| purpose | <code>string</code> | A system variable that states the purpose of the event. |
+| [ref_id] | <code>string</code> | Custom unique value that identifies result of processed operation. |
+| [form_valid] | <code>boolean</code> | Indicates wether or not the form is valid. |
+| [invalid_fields] | <code>Array.&lt;string&gt;</code> | Names of form fields with invalid data. |
+| [invalid_showed_fields] | <code>Array.&lt;string&gt;</code> | Names of invalid form fields which are already displaying the error. |
+| [validators] | <code>Partial.&lt;Record.&lt;(CardValidatorValue\|GenericValidatorValue), Array.&lt;string&gt;&gt;&gt;</code> | Object containing validator identifiers as keys and the fields subject to that validator as an array of form field names.  See list of available [Generic Vallidators](#user-content-w_GENERIC_VALIDATORS) and [Card Validators](#user-content-w_CARD_VALIDATORS), |
 
 <a name="w_IEventMetaData" id="w_IEventMetaData" href="#user-content-w_IEventMetaData">&nbsp;</a>
 
 ## IEventMetaData
-Interface of data from event.
+Contains basic information associated with the event and additional meta data
+specific to the event. E.g., card info, gateway info, etc.
 
 **Kind**: global interface  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| event | <code>string</code> | Event name |
-| purpose | <code>string</code> | System variable. Purpose of event |
-| message_source | <code>string</code> | System variable. Event source |
-| [ref_id] | <code>string</code> | Custom value for identify result of processed operation |
+| event | <code>string</code> | The name of the event. |
+| purpose | <code>string</code> | A system variable that states the purpose of the event. |
+| message_source | <code>string</code> | A system variable that identifies the event source. |
+| [ref_id] | <code>string</code> | Custom unique value that identifies result of processed operation. |
 | configuration_token | <code>string</code> | Token received from our API with widget data |
 | type | <code>string</code> | Payment type 'card', 'bank_account' |
 | gateway_type | <code>string</code> | Gateway type |
 | [card_number_last4] | <code>string</code> | Last 4 digit of your card |
-| [card_scheme] | <code>string</code> | Card scheme |
+| [card_scheme] | <code>string</code> | Card scheme, e.g., (Visa, Mastercard and American Express (AmEx)) |
 | [card_number_length] | <code>number</code> | Card number length |
 | [account_name] | <code>string</code> | Bank account account name |
 | [account_number] | <code>string</code> | Bank account account number |
@@ -152,10 +160,10 @@ Interface of data from event.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| event | <code>string</code> | Event name |
-| purpose | <code>string</code> | System variable. Purpose of event |
-| message_source | <code>string</code> | System variable. Event source |
-| [ref_id] | <code>string</code> | Custom value for identify result of processed operation |
+| event | <code>string</code> | The name of the event. |
+| purpose | <code>string</code> | A system variable that states the purpose of the event. |
+| message_source | <code>string</code> | A system variable that identifies the event source. |
+| [ref_id] | <code>string</code> | Custom unique value that identifies result of processed operation. |
 
 <a name="w_IEventFinishData" id="w_IEventFinishData" href="#user-content-w_IEventFinishData">&nbsp;</a>
 
@@ -166,10 +174,10 @@ Interface of data from event.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| event | <code>string</code> | Event name |
-| purpose | <code>string</code> | System variable. Purpose of event |
-| message_source | <code>string</code> | System variable. Event source |
-| [ref_id] | <code>string</code> | Custom value for identify result of processed operation |
+| event | <code>string</code> | The name of the event. |
+| purpose | <code>string</code> | A system variable that states the purpose of the event. |
+| message_source | <code>string</code> | A system variable that identifies the event source. |
+| [ref_id] | <code>string</code> | Custom unique value that identifies result of processed operation. |
 | payment_source | <code>string</code> | One time token. Result from this endpoint [API docs](https://docs.paydock.com/#tokens) |
 
 <a name="w_IPayPalMeta" id="w_IPayPalMeta" href="#user-content-w_IPayPalMeta">&nbsp;</a>
@@ -383,7 +391,7 @@ Class Widget include method for working on html and include extended by HtmlMult
     * [.setFormElements(elements)](#user-content-w_HtmlWidget+setFormElements)
     * [.setMeta(object)](#user-content-w_HtmlWidget+setMeta)
     * [.load()](#user-content-w_HtmlMultiWidget+load)
-    * [.on(eventName, [cb])](#user-content-w_HtmlMultiWidget+on) ⇒ <code>Promise.&lt;(IEventData\|IEventMetaData\|IEventFinishData\|IFormValidation)&gt;</code> \| <code>void</code>
+    * [.afterLoad()](#user-content-w_HtmlMultiWidget+afterLoad)
     * [.trigger(triggers, data)](#user-content-w_HtmlMultiWidget+trigger)
     * [.getValidationState()](#user-content-w_HtmlMultiWidget+getValidationState) ⇒ [<code>IFormValidation</code>](#user-content-w_IFormValidation)
     * [.isValidForm()](#user-content-w_HtmlMultiWidget+isValidForm) ⇒ <code>boolean</code>
@@ -396,6 +404,7 @@ Class Widget include method for working on html and include extended by HtmlMult
     * [.hideElements(elements)](#user-content-w_HtmlMultiWidget+hideElements)
     * [.showElements(elements)](#user-content-w_HtmlMultiWidget+showElements)
     * [.updateFormValues(fieldValues)](#user-content-w_HtmlMultiWidget+updateFormValues)
+    * [.updateFormValue(key, value)](#user-content-w_HtmlMultiWidget+updateFormValue)
     * [.onFinishInsert(selector, dataType)](#user-content-w_HtmlMultiWidget+onFinishInsert)
     * [.interceptSubmitForm(selector)](#user-content-w_HtmlMultiWidget+interceptSubmitForm)
     * [.useCheckoutAutoSubmit()](#user-content-w_HtmlMultiWidget+useCheckoutAutoSubmit)
@@ -560,51 +569,38 @@ config.setMeta({
 <a name="w_HtmlMultiWidget+load" id="w_HtmlMultiWidget+load" href="#user-content-w_HtmlMultiWidget+load">&nbsp;</a>
 
 ### htmlWidget.load()
-The final method to beginning, the load process of widget to html
+Loads the widget.
+
+Calling this method results in an iframe element being inserted and rendered in the DOM.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>load</code>](#user-content-w_HtmlMultiWidget+load)  
-<a name="w_HtmlMultiWidget+on" id="w_HtmlMultiWidget+on" href="#user-content-w_HtmlMultiWidget+on">&nbsp;</a>
+<a name="w_HtmlMultiWidget+afterLoad" id="w_HtmlMultiWidget+afterLoad" href="#user-content-w_HtmlMultiWidget+afterLoad">&nbsp;</a>
 
-### htmlWidget.on(eventName, [cb]) ⇒ <code>Promise.&lt;(IEventData\|IEventMetaData\|IEventFinishData\|IFormValidation)&gt;</code> \| <code>void</code>
-Listen to events of widget
+### htmlWidget.afterLoad()
+Registers a form validation callback for validation events.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
-**Overrides**: [<code>on</code>](#user-content-w_HtmlMultiWidget+on)  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| eventName | <code>string</code> | Available event names [EVENT](#user-content-w_EVENT) |
-| [cb] | <code>listener</code> |  |
-
-**Example**  
-
-```javascript
-widget.on('form_submit', function (data) {
-     console.log(data);
-});
-// or
- widget.on('form_submit').then(function (data) {
-     console.log(data);
-});
-```
+**Overrides**: [<code>afterLoad</code>](#user-content-w_HtmlMultiWidget+afterLoad)  
 <a name="w_HtmlMultiWidget+trigger" id="w_HtmlMultiWidget+trigger" href="#user-content-w_HtmlMultiWidget+trigger">&nbsp;</a>
 
 ### htmlWidget.trigger(triggers, data)
-This callback will be called for every trigger
+Registers callback that will be invoked for every trigger.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>trigger</code>](#user-content-w_HtmlMultiWidget+trigger)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| triggers | <code>triggerName</code> | submit_form, tab |
-| data | [<code>ITriggerData</code>](#user-content-w_ITriggerData) | which will be sending to widget |
+| triggers | <code>&#x27;submit\_form&#x27;</code> \| <code>&#x27;tab&#x27;</code> | The Widget element identifier that caused the trigger. |
+| data | [<code>ITriggerData</code>](#user-content-w_ITriggerData) | Data that will be sent to the widget when the trigger occurs. |
 
 <a name="w_HtmlMultiWidget+getValidationState" id="w_HtmlMultiWidget+getValidationState" href="#user-content-w_HtmlMultiWidget+getValidationState">&nbsp;</a>
 
 ### htmlWidget.getValidationState() ⇒ [<code>IFormValidation</code>](#user-content-w_IFormValidation)
-Using this method you can get validation state information
+Gets a reference to the form current validation state.
+
+!Warning: do not directly modify the values of the returned object.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>getValidationState</code>](#user-content-w_HtmlMultiWidget+getValidationState)  
@@ -612,11 +608,13 @@ Using this method you can get validation state information
 <a name="w_HtmlMultiWidget+isValidForm" id="w_HtmlMultiWidget+isValidForm" href="#user-content-w_HtmlMultiWidget+isValidForm">&nbsp;</a>
 
 ### htmlWidget.isValidForm() ⇒ <code>boolean</code>
-Using this method you can check if the form is valid
+Checks if a given form is valid.
+
+A form is valid if all form fields are valid.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>isValidForm</code>](#user-content-w_HtmlMultiWidget+isValidForm)  
-**Returns**: <code>boolean</code> - Form is valid  
+**Returns**: <code>boolean</code> - Indicates wether or not form is valid.  
 <a name="w_HtmlMultiWidget+isInvalidField" id="w_HtmlMultiWidget+isInvalidField" href="#user-content-w_HtmlMultiWidget+isInvalidField">&nbsp;</a>
 
 ### htmlWidget.isInvalidField(field) ⇒ <code>boolean</code>
@@ -633,92 +631,96 @@ Using this method you can check if a specific form field is invalid
 <a name="w_HtmlMultiWidget+isFieldErrorShowed" id="w_HtmlMultiWidget+isFieldErrorShowed" href="#user-content-w_HtmlMultiWidget+isFieldErrorShowed">&nbsp;</a>
 
 ### htmlWidget.isFieldErrorShowed(field) ⇒ <code>boolean</code>
-Using this method you can check if an error is displayed on a specific field
+Checks if a given form field is displaying an error.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>isFieldErrorShowed</code>](#user-content-w_HtmlMultiWidget+isFieldErrorShowed)  
-**Returns**: <code>boolean</code> - Error is showed on field  
+**Returns**: <code>boolean</code> - Indicates wether or not the Error message is being displayed on the associated field.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| field | <code>string</code> | Field name |
+| field | <code>string</code> | The form field name |
 
 <a name="w_HtmlMultiWidget+isInvalidFieldByValidator" id="w_HtmlMultiWidget+isInvalidFieldByValidator" href="#user-content-w_HtmlMultiWidget+isInvalidFieldByValidator">&nbsp;</a>
 
 ### htmlWidget.isInvalidFieldByValidator(field, validator) ⇒ <code>boolean</code>
-Using this method you can check if a specific field is invalid
+Checks if a given form field is valid or invalid by name.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>isInvalidFieldByValidator</code>](#user-content-w_HtmlMultiWidget+isInvalidFieldByValidator)  
-**Returns**: <code>boolean</code> - Field is invalid by validator  
+**Returns**: <code>boolean</code> - Indicates wether or not the field is invalid based on validator intepretation.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| field | <code>string</code> | Field name |
-| validator | <code>string</code> | Validator name. Available validators: `required, cardNumberValidator, expireDateValidation` |
+| field | <code>string</code> | The form field name |
+| validator |  | The name of the validator. |
 
 <a name="w_HtmlMultiWidget+hide" id="w_HtmlMultiWidget+hide" href="#user-content-w_HtmlMultiWidget+hide">&nbsp;</a>
 
 ### htmlWidget.hide([saveSize])
-Using this method you can hide widget after load
+Hides the widget.
+
+E.g., use this method to hide the widget after it loads.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>hide</code>](#user-content-w_HtmlMultiWidget+hide)  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| [saveSize] | <code>boolean</code> | <code>false</code> | using this param you can save iframe's size |
+| [saveSize] | <code>boolean</code> | <code>false</code> | Wether the original iframe element size should be saved before being hidden. |
 
 <a name="w_HtmlMultiWidget+show" id="w_HtmlMultiWidget+show" href="#user-content-w_HtmlMultiWidget+show">&nbsp;</a>
 
 ### htmlWidget.show()
-Using this method you can show widget after using hide method
+Shows the widget.
+
+E.g., use this method to show the widget after it was explicitly hidden.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>show</code>](#user-content-w_HtmlMultiWidget+show)  
 <a name="w_HtmlMultiWidget+reload" id="w_HtmlMultiWidget+reload" href="#user-content-w_HtmlMultiWidget+reload">&nbsp;</a>
 
 ### htmlWidget.reload()
-Using this method you can reload widget
+Reloads the widget.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>reload</code>](#user-content-w_HtmlMultiWidget+reload)  
 <a name="w_HtmlMultiWidget+hideElements" id="w_HtmlMultiWidget+hideElements" href="#user-content-w_HtmlMultiWidget+hideElements">&nbsp;</a>
 
 ### htmlWidget.hideElements(elements)
-Using this method you can hide any elements inside widget
+Hides the specified Widget elements by their identifier.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>hideElements</code>](#user-content-w_HtmlMultiWidget+hideElements)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| elements | <code>Array.&lt;string&gt;</code> | list of element which can be hidden [ELEMENT](#user-content-w_ELEMENT) || [FORM_FIELD](#user-content-w_FORM_FIELD) |
+| elements | <code>Array.&lt;string&gt;</code> | List of element which can be hidden [ELEMENT](#user-content-w_ELEMENT) || [FORM_FIELD](#user-content-w_FORM_FIELD) |
 
 **Example**  
-
 ```javascript
 widget.hideElements(['submit_button', 'email']);
 ```
 <a name="w_HtmlMultiWidget+showElements" id="w_HtmlMultiWidget+showElements" href="#user-content-w_HtmlMultiWidget+showElements">&nbsp;</a>
 
 ### htmlWidget.showElements(elements)
-Using this method you can show any elements inside widget
-
-* @example
-widget.showElements(['submit_button', 'email']);
+Shows the specified Widget elements by their identifier.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>showElements</code>](#user-content-w_HtmlMultiWidget+showElements)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| elements | <code>Array.&lt;string&gt;</code> | list of element which can be showed [ELEMENT](#user-content-w_ELEMENT) || [FORM_FIELD](#user-content-w_FORM_FIELD) |
+| elements | <code>Array.&lt;string&gt;</code> | List of elements which can be showed [ELEMENT](#user-content-w_ELEMENT) || [FORM_FIELD](#user-content-w_FORM_FIELD) |
 
+**Example**  
+```javascript
+widget.showElements(['submit_button', 'email']);
+```
 <a name="w_HtmlMultiWidget+updateFormValues" id="w_HtmlMultiWidget+updateFormValues" href="#user-content-w_HtmlMultiWidget+updateFormValues">&nbsp;</a>
 
 ### htmlWidget.updateFormValues(fieldValues)
-Method for update values for form fields inside the widget
+Updates the form field values inside the widget.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>updateFormValues</code>](#user-content-w_HtmlMultiWidget+updateFormValues)  
@@ -728,53 +730,71 @@ Method for update values for form fields inside the widget
 | fieldValues | <code>IFormValues</code> | Fields with values |
 
 **Example**  
-
 ```javascript
 widget.updateFormValues({
-      email: 'predefined@email.com',
-      card_name: 'Houston'
-  });
+  email: 'predefined@email.com',
+  card_name: 'Houston'
+});
+```
+<a name="w_HtmlMultiWidget+updateFormValue" id="w_HtmlMultiWidget+updateFormValue" href="#user-content-w_HtmlMultiWidget+updateFormValue">&nbsp;</a>
+
+### htmlWidget.updateFormValue(key, value)
+Updates a single form field values inside the widget by the form field name.
+
+**Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
+**Overrides**: [<code>updateFormValue</code>](#user-content-w_HtmlMultiWidget+updateFormValue)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>string</code> | The form field name |
+| value | <code>string</code> | The form field value |
+
+**Example**  
+```javascript
+widget.updateFormValue("card_name", "John Doe");
 ```
 <a name="w_HtmlMultiWidget+onFinishInsert" id="w_HtmlMultiWidget+onFinishInsert" href="#user-content-w_HtmlMultiWidget+onFinishInsert">&nbsp;</a>
 
 ### htmlWidget.onFinishInsert(selector, dataType)
-After finish event of widget, data (dataType) will be insert to input (selector)
+Inserts the event data (after finish event) onto the input field associated with the provided CSS selector.
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>onFinishInsert</code>](#user-content-w_HtmlMultiWidget+onFinishInsert)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| selector | <code>string</code> | css selector . [] # |
-| dataType | <code>string</code> | data type of IEventData object. |
+| selector | <code>string</code> | A CSS selector. E.g., ".my-class", "#my-id", or others |
+| dataType | <code>string</code> | The data type of IEventData object. |
 
 <a name="w_HtmlMultiWidget+interceptSubmitForm" id="w_HtmlMultiWidget+interceptSubmitForm" href="#user-content-w_HtmlMultiWidget+interceptSubmitForm">&nbsp;</a>
 
 ### htmlWidget.interceptSubmitForm(selector)
-Widget will intercept submit of your form for processing widget
+Intercepts a form submission and delegates processing to the widget.
 
-Process: click by submit button in your form --> submit widget ---> submit your form
+An simplified example of the process:
+- User clicks submit button in your form
+- This implicitly triggers a submission to the widget
+- The widget submits your form
 
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>interceptSubmitForm</code>](#user-content-w_HtmlMultiWidget+interceptSubmitForm)  
-**Note**: submit button in widget will be hidden.  
+**Note**: The widget's submit button will be hidden.  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | selector | <code>string</code> | css selector of your form |
 
 **Example**  
-
-```javascript
-<form id="myForm">
+```html
+<body>
+ <form id="myForm">
      <input name="amount">
      <button type="submit">Submit</button>
  </form>
-<!--
--->
-<script>
+ <script>
     widget.interceptSubmitForm('#myForm');
-</script>
+ </script>
+</body>
 ```
 <a name="w_HtmlMultiWidget+useCheckoutAutoSubmit" id="w_HtmlMultiWidget+useCheckoutAutoSubmit" href="#user-content-w_HtmlMultiWidget+useCheckoutAutoSubmit">&nbsp;</a>
 
@@ -791,7 +811,6 @@ Use this method for resize iFrame according content height
 **Kind**: instance method of [<code>HtmlWidget</code>](#user-content-w_HtmlWidget)  
 **Overrides**: [<code>useAutoResize</code>](#user-content-w_HtmlMultiWidget+useAutoResize)  
 **Example**  
-
 ```javascript
 widget.useAutoResize();
 ```
@@ -1096,7 +1115,7 @@ Class HtmlMultiWidget include method for working with html
 * [HtmlMultiWidget](#user-content-w_HtmlMultiWidget) ⇐ [<code>MultiWidget</code>](#user-content-w_MultiWidget)
     * [new HtmlMultiWidget(selector, publicKey, conf)](#user-content-w_new_HtmlMultiWidget_new)
     * [.load()](#user-content-w_HtmlMultiWidget+load)
-    * [.on(eventName, [cb])](#user-content-w_HtmlMultiWidget+on) ⇒ <code>Promise.&lt;(IEventData\|IEventMetaData\|IEventFinishData\|IFormValidation)&gt;</code> \| <code>void</code>
+    * [.afterLoad()](#user-content-w_HtmlMultiWidget+afterLoad)
     * [.trigger(triggers, data)](#user-content-w_HtmlMultiWidget+trigger)
     * [.getValidationState()](#user-content-w_HtmlMultiWidget+getValidationState) ⇒ [<code>IFormValidation</code>](#user-content-w_IFormValidation)
     * [.isValidForm()](#user-content-w_HtmlMultiWidget+isValidForm) ⇒ <code>boolean</code>
@@ -1109,6 +1128,7 @@ Class HtmlMultiWidget include method for working with html
     * [.hideElements(elements)](#user-content-w_HtmlMultiWidget+hideElements)
     * [.showElements(elements)](#user-content-w_HtmlMultiWidget+showElements)
     * [.updateFormValues(fieldValues)](#user-content-w_HtmlMultiWidget+updateFormValues)
+    * [.updateFormValue(key, value)](#user-content-w_HtmlMultiWidget+updateFormValue)
     * [.onFinishInsert(selector, dataType)](#user-content-w_HtmlMultiWidget+onFinishInsert)
     * [.interceptSubmitForm(selector)](#user-content-w_HtmlMultiWidget+interceptSubmitForm)
     * [.useCheckoutAutoSubmit()](#user-content-w_HtmlMultiWidget+useCheckoutAutoSubmit)
@@ -1159,58 +1179,47 @@ var widget = new MultiWidget('#widget', 'publicKey',[ With Configurations
 <a name="w_HtmlMultiWidget+load" id="w_HtmlMultiWidget+load" href="#user-content-w_HtmlMultiWidget+load">&nbsp;</a>
 
 ### htmlMultiWidget.load()
-The final method to beginning, the load process of widget to html
-
-**Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
-<a name="w_HtmlMultiWidget+on" id="w_HtmlMultiWidget+on" href="#user-content-w_HtmlMultiWidget+on">&nbsp;</a>
+Loads the widget.
 
-### htmlMultiWidget.on(eventName, [cb]) ⇒ <code>Promise.&lt;(IEventData\|IEventMetaData\|IEventFinishData\|IFormValidation)&gt;</code> \| <code>void</code>
-Listen to events of widget
+Calling this method results in an iframe element being inserted and rendered in the DOM.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
+<a name="w_HtmlMultiWidget+afterLoad" id="w_HtmlMultiWidget+afterLoad" href="#user-content-w_HtmlMultiWidget+afterLoad">&nbsp;</a>
 
-| Param | Type | Description |
-| --- | --- | --- |
-| eventName | <code>string</code> | Available event names [EVENT](#user-content-w_EVENT) |
-| [cb] | <code>listener</code> |  |
-
-**Example**  
+### htmlMultiWidget.afterLoad()
+Registers a form validation callback for validation events.
 
-```javascript
-widget.on('form_submit', function (data) {
-     console.log(data);
-});
-// or
- widget.on('form_submit').then(function (data) {
-     console.log(data);
-});
-```
+**Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 <a name="w_HtmlMultiWidget+trigger" id="w_HtmlMultiWidget+trigger" href="#user-content-w_HtmlMultiWidget+trigger">&nbsp;</a>
 
 ### htmlMultiWidget.trigger(triggers, data)
-This callback will be called for every trigger
+Registers callback that will be invoked for every trigger.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| triggers | <code>triggerName</code> | submit_form, tab |
-| data | [<code>ITriggerData</code>](#user-content-w_ITriggerData) | which will be sending to widget |
+| triggers | <code>&#x27;submit\_form&#x27;</code> \| <code>&#x27;tab&#x27;</code> | The Widget element identifier that caused the trigger. |
+| data | [<code>ITriggerData</code>](#user-content-w_ITriggerData) | Data that will be sent to the widget when the trigger occurs. |
 
 <a name="w_HtmlMultiWidget+getValidationState" id="w_HtmlMultiWidget+getValidationState" href="#user-content-w_HtmlMultiWidget+getValidationState">&nbsp;</a>
 
 ### htmlMultiWidget.getValidationState() ⇒ [<code>IFormValidation</code>](#user-content-w_IFormValidation)
-Using this method you can get validation state information
+Gets a reference to the form current validation state.
+
+!Warning: do not directly modify the values of the returned object.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 **Returns**: [<code>IFormValidation</code>](#user-content-w_IFormValidation) - Form validation object  
 <a name="w_HtmlMultiWidget+isValidForm" id="w_HtmlMultiWidget+isValidForm" href="#user-content-w_HtmlMultiWidget+isValidForm">&nbsp;</a>
 
 ### htmlMultiWidget.isValidForm() ⇒ <code>boolean</code>
-Using this method you can check if the form is valid
+Checks if a given form is valid.
+
+A form is valid if all form fields are valid.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
-**Returns**: <code>boolean</code> - Form is valid  
+**Returns**: <code>boolean</code> - Indicates wether or not form is valid.  
 <a name="w_HtmlMultiWidget+isInvalidField" id="w_HtmlMultiWidget+isInvalidField" href="#user-content-w_HtmlMultiWidget+isInvalidField">&nbsp;</a>
 
 ### htmlMultiWidget.isInvalidField(field) ⇒ <code>boolean</code>
@@ -1226,85 +1235,89 @@ Using this method you can check if a specific form field is invalid
 <a name="w_HtmlMultiWidget+isFieldErrorShowed" id="w_HtmlMultiWidget+isFieldErrorShowed" href="#user-content-w_HtmlMultiWidget+isFieldErrorShowed">&nbsp;</a>
 
 ### htmlMultiWidget.isFieldErrorShowed(field) ⇒ <code>boolean</code>
-Using this method you can check if an error is displayed on a specific field
+Checks if a given form field is displaying an error.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
-**Returns**: <code>boolean</code> - Error is showed on field  
+**Returns**: <code>boolean</code> - Indicates wether or not the Error message is being displayed on the associated field.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| field | <code>string</code> | Field name |
+| field | <code>string</code> | The form field name |
 
 <a name="w_HtmlMultiWidget+isInvalidFieldByValidator" id="w_HtmlMultiWidget+isInvalidFieldByValidator" href="#user-content-w_HtmlMultiWidget+isInvalidFieldByValidator">&nbsp;</a>
 
 ### htmlMultiWidget.isInvalidFieldByValidator(field, validator) ⇒ <code>boolean</code>
-Using this method you can check if a specific field is invalid
+Checks if a given form field is valid or invalid by name.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
-**Returns**: <code>boolean</code> - Field is invalid by validator  
+**Returns**: <code>boolean</code> - Indicates wether or not the field is invalid based on validator intepretation.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| field | <code>string</code> | Field name |
-| validator | <code>string</code> | Validator name. Available validators: `required, cardNumberValidator, expireDateValidation` |
+| field | <code>string</code> | The form field name |
+| validator |  | The name of the validator. |
 
 <a name="w_HtmlMultiWidget+hide" id="w_HtmlMultiWidget+hide" href="#user-content-w_HtmlMultiWidget+hide">&nbsp;</a>
 
 ### htmlMultiWidget.hide([saveSize])
-Using this method you can hide widget after load
+Hides the widget.
+
+E.g., use this method to hide the widget after it loads.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| [saveSize] | <code>boolean</code> | <code>false</code> | using this param you can save iframe's size |
+| [saveSize] | <code>boolean</code> | <code>false</code> | Wether the original iframe element size should be saved before being hidden. |
 
 <a name="w_HtmlMultiWidget+show" id="w_HtmlMultiWidget+show" href="#user-content-w_HtmlMultiWidget+show">&nbsp;</a>
 
 ### htmlMultiWidget.show()
-Using this method you can show widget after using hide method
+Shows the widget.
+
+E.g., use this method to show the widget after it was explicitly hidden.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 <a name="w_HtmlMultiWidget+reload" id="w_HtmlMultiWidget+reload" href="#user-content-w_HtmlMultiWidget+reload">&nbsp;</a>
 
 ### htmlMultiWidget.reload()
-Using this method you can reload widget
+Reloads the widget.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 <a name="w_HtmlMultiWidget+hideElements" id="w_HtmlMultiWidget+hideElements" href="#user-content-w_HtmlMultiWidget+hideElements">&nbsp;</a>
 
 ### htmlMultiWidget.hideElements(elements)
-Using this method you can hide any elements inside widget
+Hides the specified Widget elements by their identifier.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| elements | <code>Array.&lt;string&gt;</code> | list of element which can be hidden [ELEMENT](#user-content-w_ELEMENT) || [FORM_FIELD](#user-content-w_FORM_FIELD) |
+| elements | <code>Array.&lt;string&gt;</code> | List of element which can be hidden [ELEMENT](#user-content-w_ELEMENT) || [FORM_FIELD](#user-content-w_FORM_FIELD) |
 
 **Example**  
-
 ```javascript
 widget.hideElements(['submit_button', 'email']);
 ```
 <a name="w_HtmlMultiWidget+showElements" id="w_HtmlMultiWidget+showElements" href="#user-content-w_HtmlMultiWidget+showElements">&nbsp;</a>
 
 ### htmlMultiWidget.showElements(elements)
-Using this method you can show any elements inside widget
-
-* @example
-widget.showElements(['submit_button', 'email']);
+Shows the specified Widget elements by their identifier.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| elements | <code>Array.&lt;string&gt;</code> | list of element which can be showed [ELEMENT](#user-content-w_ELEMENT) || [FORM_FIELD](#user-content-w_FORM_FIELD) |
+| elements | <code>Array.&lt;string&gt;</code> | List of elements which can be showed [ELEMENT](#user-content-w_ELEMENT) || [FORM_FIELD](#user-content-w_FORM_FIELD) |
 
+**Example**  
+```javascript
+widget.showElements(['submit_button', 'email']);
+```
 <a name="w_HtmlMultiWidget+updateFormValues" id="w_HtmlMultiWidget+updateFormValues" href="#user-content-w_HtmlMultiWidget+updateFormValues">&nbsp;</a>
 
 ### htmlMultiWidget.updateFormValues(fieldValues)
-Method for update values for form fields inside the widget
+Updates the form field values inside the widget.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 
@@ -1313,51 +1326,68 @@ Method for update values for form fields inside the widget
 | fieldValues | <code>IFormValues</code> | Fields with values |
 
 **Example**  
-
 ```javascript
 widget.updateFormValues({
-      email: 'predefined@email.com',
-      card_name: 'Houston'
-  });
+  email: 'predefined@email.com',
+  card_name: 'Houston'
+});
+```
+<a name="w_HtmlMultiWidget+updateFormValue" id="w_HtmlMultiWidget+updateFormValue" href="#user-content-w_HtmlMultiWidget+updateFormValue">&nbsp;</a>
+
+### htmlMultiWidget.updateFormValue(key, value)
+Updates a single form field values inside the widget by the form field name.
+
+**Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>string</code> | The form field name |
+| value | <code>string</code> | The form field value |
+
+**Example**  
+```javascript
+widget.updateFormValue("card_name", "John Doe");
 ```
 <a name="w_HtmlMultiWidget+onFinishInsert" id="w_HtmlMultiWidget+onFinishInsert" href="#user-content-w_HtmlMultiWidget+onFinishInsert">&nbsp;</a>
 
 ### htmlMultiWidget.onFinishInsert(selector, dataType)
-After finish event of widget, data (dataType) will be insert to input (selector)
+Inserts the event data (after finish event) onto the input field associated with the provided CSS selector.
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| selector | <code>string</code> | css selector . [] # |
-| dataType | <code>string</code> | data type of IEventData object. |
+| selector | <code>string</code> | A CSS selector. E.g., ".my-class", "#my-id", or others |
+| dataType | <code>string</code> | The data type of IEventData object. |
 
 <a name="w_HtmlMultiWidget+interceptSubmitForm" id="w_HtmlMultiWidget+interceptSubmitForm" href="#user-content-w_HtmlMultiWidget+interceptSubmitForm">&nbsp;</a>
 
 ### htmlMultiWidget.interceptSubmitForm(selector)
-Widget will intercept submit of your form for processing widget
+Intercepts a form submission and delegates processing to the widget.
 
-Process: click by submit button in your form --> submit widget ---> submit your form
+An simplified example of the process:
+- User clicks submit button in your form
+- This implicitly triggers a submission to the widget
+- The widget submits your form
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
-**Note**: submit button in widget will be hidden.  
+**Note**: The widget's submit button will be hidden.  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | selector | <code>string</code> | css selector of your form |
 
 **Example**  
-
-```javascript
-<form id="myForm">
+```html
+<body>
+ <form id="myForm">
      <input name="amount">
      <button type="submit">Submit</button>
  </form>
-<!--
--->
-<script>
+ <script>
     widget.interceptSubmitForm('#myForm');
-</script>
+ </script>
+</body>
 ```
 <a name="w_HtmlMultiWidget+useCheckoutAutoSubmit" id="w_HtmlMultiWidget+useCheckoutAutoSubmit" href="#user-content-w_HtmlMultiWidget+useCheckoutAutoSubmit">&nbsp;</a>
 
@@ -1372,7 +1402,6 @@ Use this method for resize iFrame according content height
 
 **Kind**: instance method of [<code>HtmlMultiWidget</code>](#user-content-w_HtmlMultiWidget)  
 **Example**  
-
 ```javascript
 widget.useAutoResize();
 ```
@@ -2425,6 +2454,32 @@ Current constant include available states of element for styling
 | FOCUS | <code>string</code> | <code>&quot;focus&quot;</code> | focus. This state applies to: input |
 | HOVER | <code>string</code> | <code>&quot;hover&quot;</code> | focus. This state applies to: submit_button |
 
+<a name="w_CARD_VALIDATORS" id="w_CARD_VALIDATORS" href="#user-content-w_CARD_VALIDATORS">&nbsp;</a>
+
+## CARD\_VALIDATORS : <code>Record.&lt;string, string&gt;</code>
+List of available form field validators dedicated to cards and their definition
+
+**Kind**: global constant  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| CVV | <code>string</code> | <code>&quot;cardCvvValidation&quot;</code> | Asserts that CVV contains zero or more digits and is a number |
+| EXPIRY_DATE | <code>string</code> | <code>&quot;expireDateValidation&quot;</code> | Asserts value is a date in the future with format MM/YY |
+| HOLDER_NAME | <code>string</code> | <code>&quot;cardHoldernameValidation&quot;</code> | Asserts value is a name that respects the ITU-T T.50 standard (@see https://www.itu.int/rec/T-REC-T.50/en) |
+| NUMBER | <code>string</code> | <code>&quot;cardNumberValidation&quot;</code> | Asserts the value matches a known card scheme and as a the correct length.     E.g., matches a 13, 16 or 19 digit bank card, **or**, a 13 to 25 digit Vii Gift card |
+| PIN | <code>string</code> | <code>&quot;cardPinValidation&quot;</code> | Asserts the value is a number with exactly 4 digits |
+
+<a name="w_GENERIC_VALIDATORS" id="w_GENERIC_VALIDATORS" href="#user-content-w_GENERIC_VALIDATORS">&nbsp;</a>
+
+## GENERIC\_VALIDATORS : <code>Record.&lt;string, string&gt;</code>
+List of available generic form field validators and their definition
+
+**Kind**: global constant  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| REQUIRED | <code>string</code> | <code>&quot;required&quot;</code> | Asserts the input or form field has a value defined truthy value |
+
 <a name="w_TRIGGER" id="w_TRIGGER" href="#user-content-w_TRIGGER">&nbsp;</a>
 
 ## TRIGGER : <code>object</code>