@paydock/client-sdk 1.112.0 → 1.112.4-beta

package/slate.md

@@ -73,7 +73,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>
 ```
@@ -1481,7 +1526,7 @@ _(Required `meta` fields: - . Optional `meta` fields: -)_
         },
 	);
     button.setEnv('sandbox');
-    button.onUnavailable(() => console.log("No wallet buttons available"));
+    button.onUnavailable((data) => console.log("No wallet buttons available"));
     button.onPaymentSuccessful((data) => console.log("The payment was successful"));
     button.onPaymentError((data) => console.log("The payment was not successful"));
     button.onAuthTokensChanged((data) => console.log('Authentication tokens changed'));
@@ -1922,3 +1967,200 @@ src.setStyles({
     font_family: 'Arial',
 });
 ```
+
+# 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>
+  <style>
+    body {
+      min-width: 320px;
+      max-width: 1440px;
+      min-height: 100svh;
+    }
+
+    main {
+      padding: 2rem;
+      margin: 0 auto;
+    }
+
+    .forter-test {
+      padding: 1rem;
+      border-radius: 8px;
+      background: #f5f5f5;
+    }
+
+    .status-card {
+      background: white;
+      padding: 1rem;
+      border-radius: 4px;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+
+    .status {
+      display: inline-block;
+      padding: 0.25rem 0.5rem;
+      border-radius: 4px;
+      font-weight: 500;
+    }
+
+    .status.success {
+      background: #e6ffe6;
+      color: #006600;
+    }
+
+    .status.pending {
+      background: rgb(255, 249, 205);
+      color: rgb(255, 204, 0);
+    }
+
+    .status.error {
+      background: #ffe6e6;
+      color: #cc0000;
+    }
+
+    .error {
+      display: inline-block;
+      padding: 0.25rem 0.5rem;
+      border-radius: 4px;
+      background: #ffe6e6;
+      color: #cc0000;
+      font-weight: 500;
+    }
+
+    code {
+      background: #f0f0f0;
+      padding: 0.2rem 0.4rem;
+      border-radius: 4px;
+      font-family: monospace;
+    }
+  </style>
+</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 { FraudPreventionEvents, 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(FraudPreventionEvents.namespace, (event) => {
+      switch (event.detail.type) {
+        case FraudPreventionEvents.types.fingerprintTokenReady: {
+          token = event.detail.payload.token;
+          break;
+        }
+        case FraudPreventionEvents.types.fingerprintTokenError: {
+          errorCode = event.detail.payload.code;
+          break;
+        }
+        default: {
+          throw new Error(
+            `${FraudPreventionEvents.namespace} emitted an unsupported event: ${JSON.stringify(event.detail)}.`,
+          );
+        }
+      }
+
+      render();
+    });
+
+    new FraudPreventionService().withForter({
+      siteId: 'YOUR_SITE_ID_OR_SUBSITE_ID',
+      mode: 'test',
+      csp: false, // set 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`, `script-src-element` 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
+script-src-elem https://*.forter.com https://dlthst9q2beh8.cloudfront.net https://d2nww8zpyj5pk0.cloudfront.net https://d2w2nqfk3z9hdt.cloudfront.net
+worker-src blob:
+```