@paydock/client-sdk 1.116.0-beta → 1.116.6-beta

package/README.md

@@ -59,7 +59,7 @@ const widget = new Paydock.HtmlWidget('#selector', 'publicKey', 'gatewayId');
 ```
 
 ```js
-// default import - We do not provide default exports. They are handled differently by different tools!
+// default import - Not officially supported . They are handled differently by different tools / settings!
  ❌
 import paydock from '@paydock/client-sdk'
 >>> "Uncaught SyntaxError: The requested module does not provide an export named 'default'"
@@ -199,6 +199,20 @@ 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
+
+```javascript
+widget.on('error', (error) => {
+    const errorDiv = document.getElementById('error');
+    const errorMessage = document.getElementById('error-message');
+    
+    errorMessage.textContent = error.data.message;
+    errorDiv.style.display = 'block';
+});
+```
+
+
 ### Full example
 
 ```html
@@ -214,7 +228,34 @@ This example shows how you can use a lot of other methods to settings your form
     <div id="widget"
         widget-style="text-color: #FFFFAA; border-color: #yellow"
         title="Payment form"
-        finish-text="Payment resource was successfully accepted"></div>
+        finish-text="Payment resource was successfully accepted">
+    </div>
+
+    <div 
+        id="error" 
+        style="
+            display: none;
+            max-width: 600px;
+            margin: 16px auto;
+            padding: 16px 20px;
+            border-radius: 8px;
+            background-color: #FEF2F2;
+            border: 1px solid #FEE2E2;
+            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+            font-family: system-ui, -apple-system, sans-serif;
+            color: #991B1B;
+            line-height: 1.5;
+            font-size: 14px;
+        "
+        title="error"
+        >
+        <div style="display: flex; align-items: flex-start; gap: 12px;">
+            <div>
+                <h4 style="margin: 0 0 4px 0; font-size: 14px; font-weight: 600;">Access Error</h4>
+                <div id="error-message"></div>
+            </div>
+        </div>
+    </div> 
 </form>
 
 <script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
@@ -224,11 +265,15 @@ This example shows how you can use a lot of other methods to settings your form
 	widget.setSupportedCardIcons(['mastercard', 'visa']);
 	widget.setFormFields(['phone', 'email']);
 	widget.setRefId('custom-ref-id');
-    widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');z
+    widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
 
+    widget.on('error', (error) => {
+        document.getElementById('error-message').textContent = error.data.message;
+        document.getElementById('error').style.display = 'block';
+    });
 	widget.load();
 </script>
-</script>
+
 </body>
 </html>
 ```
@@ -250,6 +295,14 @@ This example shows how you can use a lot of other methods to settings your form
 </dd>
 </dl>
 
+## Members
+
+<dl>
+<dt><a href="#user-content-w_PURPOSE">PURPOSE</a> : <code>object</code></dt>
+<dd><p>Purposes</p>
+</dd>
+</dl>
+
 ## Constants
 
 <dl>
@@ -262,9 +315,6 @@ This example shows how you can use a lot of other methods to settings your form
 <dt><a href="#user-content-w_PAYMENT_TYPE">PAYMENT_TYPE</a> : <code>object</code></dt>
 <dd><p>List of available payment source types</p>
 </dd>
-<dt><a href="#user-content-w_PURPOSE">PURPOSE</a> : <code>object</code></dt>
-<dd><p>Purposes</p>
-</dd>
 <dt><a href="#user-content-w_FORM_FIELD">FORM_FIELD</a> : <code>object</code></dt>
 <dd><p>Current constant include available type of fields which can be included to widget</p>
 </dd>
@@ -796,10 +846,10 @@ The method to set meta information for the checkout page
 
 ```javascript
 config.setMeta({
-            brand_name: 'paydock',
-            reference: '15',
-            email: 'wault@paydock.com'
-        });
+              brand_name: 'paydock',
+              reference: '15',
+              email: 'wault@paydock.com'
+          });
 ```
 <a name="w_HtmlMultiWidget+load" id="w_HtmlMultiWidget+load" href="#user-content-w_HtmlMultiWidget+load">&nbsp;</a>
 
@@ -2502,6 +2552,19 @@ Method for setting a custom language code
 ```javascript
 config.setLanguage('en');
 ```
+<a name="w_PURPOSE" id="w_PURPOSE" href="#user-content-w_PURPOSE">&nbsp;</a>
+
+## PURPOSE : <code>object</code>
+Purposes
+
+**Kind**: global variable  
+
+| Param | Type | Default |
+| --- | --- | --- |
+| PAYMENT_SOURCE | <code>string</code> | <code>&quot;payment_source&quot;</code> | 
+| CARD_PAYMENT_SOURCE_WITH_CVV | <code>string</code> | <code>&quot;card_payment_source_with_cvv&quot;</code> | 
+| CARD_PAYMENT_SOURCE_WITHOUT_CVV | <code>string</code> | <code>&quot;card_payment_source_without_cvv&quot;</code> | 
+
 <a name="w_EVENT" id="w_EVENT" href="#user-content-w_EVENT">&nbsp;</a>
 
 ## EVENT : <code>object</code>
@@ -2551,19 +2614,6 @@ List of available payment source types
 | BANK_ACCOUNT | <code>string</code> | <code>&quot;bank_account&quot;</code> | 
 | CHECKOUT | <code>string</code> | <code>&quot;checkout&quot;</code> | 
 
-<a name="w_PURPOSE" id="w_PURPOSE" href="#user-content-w_PURPOSE">&nbsp;</a>
-
-## PURPOSE : <code>object</code>
-Purposes
-
-**Kind**: global constant  
-
-| Param | Type | Default |
-| --- | --- | --- |
-| PAYMENT_SOURCE | <code>string</code> | <code>&quot;payment_source&quot;</code> | 
-| CARD_PAYMENT_SOURCE_WITH_CVV | <code>string</code> | <code>&quot;card_payment_source_with_cvv&quot;</code> | 
-| CARD_PAYMENT_SOURCE_WITHOUT_CVV | <code>string</code> | <code>&quot;card_payment_source_without_cvv&quot;</code> | 
-
 <a name="w_FORM_FIELD" id="w_FORM_FIELD" href="#user-content-w_FORM_FIELD">&nbsp;</a>
 
 ## FORM\_FIELD : <code>object</code>
@@ -5944,6 +5994,7 @@ Interface of data used by the wallet checkout and payment proccess.
 | [amount_label] | <code>string</code> | Label shown next to the total amount to be paid. Required for [Stripe, ApplePay, GooglePay]. N/A for [FlyPay, Flypay V2, PayPal, Afterpay]. |
 | [country] | <code>string</code> | Country of the user. 2 letter ISO code format. Required for [Stripe, ApplePay, GooglePay, Afterpay]. N/A for [FlyPay, Flypay V2, PayPal]. |
 | [pay_later] | <code>boolean</code> | Used to enable Pay Later feature in PayPal Smart Checkout WalletButton integration when available. Optional for [PayPal]. N/A for other wallets. |
+| [hide_message] | <code>boolean</code> | Used to hide Pay Later message in PayPal Smart Checkout WalletButton integration. Optional for [PayPal]. N/A for other wallets. |
 | [standalone] | <code>boolean</code> | Used to enable Standalone Buttons feature in PayPal Smart Checkout WalletButton integration. Used together with `pay_later`. Optional for [PayPal]. N/A for other wallets. |
 | [show_billing_address] | <code>boolean</code> | Used to hide/show the billing address on ApplePay and GooglePay popups. Default value is false. Optional for [ApplePay, GooglePay]. N/A for other wallets. |
 | [request_payer_name] | <code>boolean</code> | Used mainly for fraud purposes - recommended set to true. Optional for [Stripe]. N/A for other wallets. |
@@ -6723,6 +6774,7 @@ For in-depth information, please refer to the [Paypal documentation](https://dev
 | amount | <code>number</code> | Total amount of the transaction. Represents the money to be charged. |
 | currency | <code>string</code> | Currency of the transaction in ISO 4217 currency code format. |
 | [pay_later] | <code>boolean</code> | Flag to enable Pay Later feature of PayPal, allowing Pay in 4. Default false. |
+| [hide_message] | <code>boolean</code> | Used to hide Pay Later message in PayPal Smart Checkout WalletButton integration. Optional for [PayPal]. N/A for other wallets. |
 | [standalone] | <code>boolean</code> | Flag to specify if the PayPal standalone button should be used. Default false. |
 | [capture] | <code>boolean</code> | Flag to specify if the transaction amount should be captured immediately or authorized for later capture. Default false. |
 | [style] | <code>object</code> | Styling configurations for the PayPal widget. |
@@ -7629,42 +7681,6 @@ src.setStyles({
 });
 ```
 
-## Recognition token
-
-In order to store user information for further payments, click to pay provides a recognition token that is used to load user information.
-If you already have a recognitionToken stored, you can use it in meta to load the user information.
-
-### Storage suggestions
-Merchant can store the tokens by dropping the token as a 1st party cookie in the browser, and must ensure to manage all the security aspects around dropping/storing the cookie by following the security standards:
-
-- `Expiration Date=` cookie should be set to expire at a max 180 days
-- `Secure` flag
-- `httpOnly` flag
-- `sameSite=` strict
-- `Value=` recognition token JWT
-
-### Example code
-
-```javascript
-var src = new paydock.ClickToPay(
-    "#checkoutIframe",
-    "service_id",
-    "paydock_public_key",
-    {
-        "recognition_token": "eyJraWQiOiIy...",
-    },
-);
-src.on('recognitionTokenRequested', (data) => {
-    console.log('Recognition token was found: ' + data.data.recognitionToken);
-    // Add recognition token to your store
-});
-
-src.on('recognitionTokenDropped', () => {
-    console.log('Recognition token was droped');
-    // Delete recognition token from your store
-});
-```
-
 ## Classes
 
 <dl>
@@ -7745,7 +7761,6 @@ Interface of data used for the Mastercard Checkout. For further information refe
 | [customer.phone.country_code] | <code>string</code> | Customer phone country code (example "1" for US). |
 | [customer.phone.phone] | <code>string</code> | Customer phone number. |
 | [unaccepted_card_type] | <code>string</code> | Used to block a specific card type. Options are 'CREDIT', 'DEBIT'. |
-| [recognition_token] | <code>string</code> | Used for Click to Pay to load user information and preferences. |
 
 <a name="EventData" id="EventData" href="#EventData">&nbsp;</a>
 
@@ -7771,6 +7786,7 @@ When the flow type is src, masked checkoutData available is also returned
 | --- | --- | --- |
 | type | <code>string</code> | type of the checkout, can be `src` or `manual`. |
 | token | <code>string</code> | one time token value. |
+| token_type | <code>string</code> | one time token type value, can be `card` or `card_scheme_token`. |
 | [checkoutData] | <code>object</code> | Optional checkout data related to the checkout information. Only available on src flow. |
 | [checkoutData.card_number_bin] | <code>string</code> | The BIN of the card used for the transaction. |
 | [checkoutData.card_number_last4] | <code>string</code> | The last four digits of the card number. |
@@ -7988,8 +8004,6 @@ List of available event's name in the Click To Pay checkout lifecycle
 | CHECKOUT_POPUP_CLOSE | <code>string</code> | <code>&quot;checkoutPopupClose&quot;</code> | Event sent when Click To Pay checkout flow is closed, regardless of embedded or windowed mode. |
 | CHECKOUT_COMPLETED | <code>string</code> | <code>&quot;checkoutCompleted&quot;</code> | Event sent on successful checkout by customer. Check [data](#EventDataCheckoutCompletedData) for more information. |
 | CHECKOUT_ERROR | <code>string</code> | <code>&quot;checkoutError&quot;</code> | Event sent on error checkout by customer. Check [data](#EventData) for more information. |
-| RECOGNITION_TOKEN_REQUESTED | <code>string</code> | <code>&quot;recognitionTokenRequested&quot;</code> | Event sent when a recognition token was found on the mastercard SDK response. |
-| RECOGNITION_TOKEN_DROPPED | <code>string</code> | <code>&quot;recognitionTokenDropped&quot;</code> | Event sent when a recognition token needs to be dropped for user be no longer remembered. |
 
 <a name="EVENT_DATA_TYPE" id="EVENT_DATA_TYPE" href="#EVENT_DATA_TYPE">&nbsp;</a>
 
@@ -8005,6 +8019,147 @@ List of available event data types
 | SUCCESS | <code>string</code> | <code>&quot;Success&quot;</code> |  |
 
 
+# Fraud prevention
+
+The Fraud Prevention module allows you to add security layers to your payment workflows
+by integrating with any of our underlying fraud prevention providers.
+
+## Real time user behavior analysis
+
+### Forter
+
+One of Forter's key features is our ability to track the user's real-time behavior on
+the site and use it to separate fraudsters from legitimate buyers. To take advantage
+of Forter's technology, a JavaScript snippet needs to be placed on EVERY page
+of your commerce site beginning with the homepage and up to and including the final
+"Thank you for your purchase" page.
+
+The integration is simple and straightforward - you only need to configure event
+listeners and then instantiate a FraudPreventionService with your site configuration.
+
+Additional setup is required in case your website uses Content Security Policies (CSP)
+
+#### Forter: Code snippet
+
+```html
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>Real time user behaviour anaylsis - Forter example</title>
+  <base href="/">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="icon" type="image/x-icon" href="favicon.ico">
+  <script src="../../../bundles/widget.umd.js"></script>
+</head>
+
+<body>
+  <main>
+    <h1>Real time user behaviour anaylsis - Forter example</h1>
+    <div class="forter-test">
+      <h2>Forter Integration Test</h2>
+      <div class="status-card">
+        <p>
+          <strong>Integration Status:</strong>
+          <span data-fraud-prevention="status-indicator" class="status pending">
+            Pending
+          </span>
+        </p>
+        <p>
+          <strong>Token Value:</strong>
+          <code data-fraud-prevention="forter-token">Not available</code>
+        </p>
+        <p data-fraud-prevention="error-container" style="display: none;">
+          <strong>Error Code:</strong>
+          <span data-fraud-prevention="error-code" class="error"></span>
+        </p>
+      </div>
+    </div>
+  </main>
+  <script>
+    const { FRAUD_PREVENTION_EVENTS, FraudPreventionService } = window.paydock
+
+    let token = '';
+    let errorCode = '';
+
+    const render = () => {
+      const statusIndicator = document.querySelector('[data-fraud-prevention="status-indicator"]');
+      const tokenValue = document.querySelector('[data-fraud-prevention="forter-token"]');
+      const errorContainer = document.querySelector('[data-fraud-prevention="error-container"]');
+      const errorCodeElement = document.querySelector('[data-fraud-prevention="error-code"]');
+
+      if (token) {
+        statusIndicator.className = 'status success';
+        statusIndicator.textContent = 'Active';
+        tokenValue.textContent = token;
+      } else {
+        statusIndicator.className = 'status pending';
+        statusIndicator.textContent = 'Pending';
+        tokenValue.textContent = 'Not available';
+      }
+
+      if (errorCode) {
+        errorCodeElement.textContent = errorCode;
+        errorContainer.style.display = 'block';
+      } else {
+        errorContainer.style.display = 'none';
+      }
+    };
+
+    document.addEventListener(FRAUD_PREVENTION_EVENTS.NAMESPACE, (event) => {
+      switch (event.detail.type) {
+        case FRAUD_PREVENTION_EVENTS.TYPES.FINGERPRINT_TOKEN_READY: {
+          token = event.detail.payload.token;
+          break;
+        }
+        case FRAUD_PREVENTION_EVENTS.TYPES.FINGERPRINT_TOKEN_READY: {
+          errorCode = event.detail.payload.code;
+          break;
+        }
+        default: {
+          throw new Error(
+            `${FRAUD_PREVENTION_EVENTS.NAMESPACE} emitted an unsupported event: ${JSON.stringify(event.detail)}.`,
+          );
+        }
+      }
+
+      render();
+    });
+
+    // Bring your own site ID
+    new FraudPreventionService().withForter({
+      siteId: 'YOUR_SITE_ID_OR_SUBSITE_ID',
+      mode: 'test',
+      csp: false, // Set to csp to true if your website uses Content-Security-Policies
+    });
+
+    // Use paydock integrated registration
+    new FraudPreventionService().withAuthorization('pk_example_...').withForter({
+      providerId: 'YOUR_PAYDOCK_FORTER_SERVICE_ID',
+      mode: 'test',
+      csp: false, // Set to csp to true if your website uses Content-Security-Policies
+    });
+  </script>
+</body>
+
+</html>
+```
+
+#### Forter: Content Security Policies
+
+If your site enforces Content Security Policies (CSP), make sure to:
+
+1. Set the `csp` option to `true` when invoking `withForter` on your `FraudPreventionService` instance.
+2. Allowlist Forter's domains on `connect-src`, `script-src` and `worker-src` as shown below.
+
+```bash
+connect-src https://*.forter.com wss://cdn0.forter.com https://d2o5idwacg3gyw.cloudfront.net https://dz8rit8v72mig.cloudfront.net https://db7q4jg5rkhk8.cloudfront.net https://1.1.1.1 https://d94qwxh6czci4.cloudfront.net https://dr6vcclmzwk74.cloudfront.net https://d6rak4b14t5gp.cloudfront.net https://d3k4bt74u9esq1.cloudfront.net https://d1ezzflfzltk6e.cloudfront.net https://d3nocrch4qti4v.cloudfront.net https://duuytoqss3gu4.cloudfront.net https://df45ay5pw60dy.cloudfront.net
+script-src https://*.forter.com https://dlthst9q2beh8.cloudfront.net https://d2nww8zpyj5pk0.cloudfront.net https://d2w2nqfk3z9hdt.cloudfront.net
+worker-src blob:
+```
+
+
 ## PayPalSavePaymentSource Widget
 
 PayPalSavePaymentSource Widget allows to obtain a Paydock one time token linked with a Paypal payment source from the customer.
@@ -8365,7 +8520,7 @@ A full description of the config parameters for [PayPalDataCollector](#PayPalDat
 <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
 <script>
     let payPalDataCollector = new paydock.PayPalDataCollector(
-        sourceWebsiteIdentifier,
+        'FLOW_ID',
         {
             mouse_movement: true
         }
@@ -8377,10 +8532,11 @@ A full description of the config parameters for [PayPalDataCollector](#PayPalDat
         console.log("On Error Callback", error);
     });
 
-    const collectedDeviceData = await payPalDataCollector.collectDeviceData();
-
-    //Here when the promise is resolved, it should be able to see the correlation_id.
-    const correlationId = collectedDeviceData.correlation_id
+    payPalDataCollector.collectDeviceData().then(function(collectedDeviceData) {
+      //Here when the promise is resolved, it should be able to see the correlation_id.
+      const correlationId = collectedDeviceData.correlation_id;
+      console.log("On Success", correlationId);
+    });
 </script>
 </html>
 ```
@@ -8456,19 +8612,19 @@ PayPal Data Collector Widget constructor
 **Kind**: global class  
 
 * [PayPalDataCollector](#PayPalDataCollector)
-    * [new PayPalDataCollector(flowId, config)](#new_PayPalDataCollector_new)
+    * [new PayPalDataCollector([flowId], [config])](#new_PayPalDataCollector_new)
     * [.collectDeviceData()](#PayPalDataCollector+collectDeviceData) ⇒ [<code>Promise.&lt;CollectedDeviceData&gt;</code>](#CollectedDeviceData)
     * [.onError([callback])](#PayPalDataCollector+onError)
     * [.setEnv(env)](#PayPalDataCollector+setEnv)
 
 <a name="new_PayPalDataCollector_new" id="new_PayPalDataCollector_new" href="#new_PayPalDataCollector_new">&nbsp;</a>
 
-### new PayPalDataCollector(flowId, config)
+### new PayPalDataCollector([flowId], [config])
 
 | Param | Type | Description |
 | --- | --- | --- |
-| flowId | <code>string</code> | This string identifies the source website of the FraudNet request. |
-| config | [<code>PayPalDataCollectorConfig</code>](#PayPalDataCollectorConfig) | Extra configuration for the widget. |
+| [flowId] | <code>string</code> | This string identifies the source website of the FraudNet request. |
+| [config] | [<code>PayPalDataCollectorConfig</code>](#PayPalDataCollectorConfig) | Extra configuration for the widget. |
 
 **Example**  
 ```js
@@ -8478,10 +8634,10 @@ var payPalDataCollector = new PayPalDataCollector('FLOW_ID', {});
 
 ### payPalDataCollector.collectDeviceData() ⇒ [<code>Promise.&lt;CollectedDeviceData&gt;</code>](#CollectedDeviceData)
 After configuring the PayPalDataCollector Widget, starts the process and returns
-the correlation id used among the requests.
+the correlation id used among the requests asynchronously.
 
 **Kind**: instance method of [<code>PayPalDataCollector</code>](#PayPalDataCollector)  
-**Returns**: [<code>Promise.&lt;CollectedDeviceData&gt;</code>](#CollectedDeviceData) - Promise when resolved, returnsa an object
+**Returns**: [<code>Promise.&lt;CollectedDeviceData&gt;</code>](#CollectedDeviceData) - Promise when resolved, returns an object
 that contains the `correlation_id` key.  
 **Example**  
 ```js