@justifi/webcomponents 6.5.1-rc.3 → 6.5.1-rc.5

package/docs/payment-facilitation/dispute-management/index.mdx

@@ -0,0 +1,98 @@
+---
+id: payment-facilitation/dispute-management/index
+title: Dispute Management
+description: Operator console for reviewing and responding to card disputes.
+sidebar_position: 34
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render notification of disputed payments and allow platform to respond to dispute via form submission.
+
+## Usage
+
+<pre><code className="language-html">{`<justifi-dispute-management
+  account-id="acc_123"
+  auth-token="wct_disputes"
+  dispute-id="dp_456"
+/>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Authorizes access to disputes for a platform or merchant.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `write:disputes` scope.',
+    },
+    {
+      name: 'dispute-id',
+      type: 'string',
+      required: true,
+      description: 'Specific dispute to review/respond to.',
+    },
+    {
+      name: 'read-only',
+      type: 'boolean',
+      defaultValue: 'false',
+      description: 'Disable response actions when true.',
+    },
+  ]) }} />
+
+### Events
+
+- `evidence-uploaded`: Fires when users add files or notes.
+- `status-changed`: Indicates dispute submission or withdrawal.
+- `error-event`: Captures upload or API issues.
+
+### Public methods
+
+1. `refresh()` – Reload in-progress disputes to reflect new deadlines or statuses.
+
+## Theming & Layout
+
+<div dangerouslySetInnerHTML={{ __html: PartsTable([
+    {
+      name: 'font-family',
+      description: 'Controls the font family for the component.',
+    },
+    {
+      name: 'color',
+      description: 'Controls the text color.',
+    },
+    {
+      name: 'background-color',
+      description: 'Controls the background color.',
+    },
+    {
+      name: 'button',
+      description: 'Button styles.',
+    },
+    {
+      name: 'button-secondary',
+      description: 'Secondary button styles.',
+    },
+    {
+      name: 'button-disabled',
+      description: 'Disabled button styles.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Listening for evidence uploads
+
+<pre><code className="language-js">{`const disputes = document.querySelector('justifi-dispute-management');
+
+disputes.addEventListener('evidence-uploaded', ({ detail }) => {
+toast.success('Uploaded ' + detail.file_name);
+});`}</code></pre>

package/docs/payment-facilitation/index.mdx

@@ -0,0 +1,21 @@
+---
+id: payment-facilitation/index
+title: Payment Facilitation
+description: Core flows for capturing, refunding, and managing disputes.
+---
+
+Build an end-to-end payment experience by combining these focused guides:
+
+1. [Unified Fintech Checkout™](./unified-fintech-checkout™/index) – the
+   full-stack checkout shell for authorization and capture.
+2. [Tokenize Payment Method](./tokenize-payment-method/index) – vault cards or
+   bank accounts for future use.
+3. [Refund Payment](./refund-payment/index) – return funds with audit-friendly
+   status updates.
+4. [Dispute Management](./dispute-management/index) – monitor chargebacks and
+   submit compelling evidence.
+
+> Once your payment-facilitation configuration is live, tie it into
+> `[Entities](../entities/index)` and `[Merchant Tools](../merchant-tools/index)`
+> to keep back-office teams in sync.
+

package/docs/payment-facilitation/refund-payment/index.mdx

@@ -0,0 +1,229 @@
+---
+id: payment-facilitation/refund-payment/index
+title: Refund Payment
+description: Guided UI for issuing full or partial refunds with reason codes and audit trails.
+sidebar_position: 33
+---
+
+import { PropsTable, PartsTable, getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render a form for partially or fully refunding a payment based on a provided payment ID.
+
+## Usage
+
+<pre><code className="language-html">{`<!DOCTYPE html>
+<html dir="ltr" lang="en">
+
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
+  <title>justifi-refund-payment</title>
+
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.esm.js"></script>
+  <script nomodule src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.js"></script>
+  <style>
+    ::part(font-family) {
+      font-family: georgia;
+    }
+
+    ::part(color) {
+      color: darkslategray;
+    }
+
+    ::part(background-color) {
+      background-color: transparent;
+    }
+
+    ::part(button) {
+      padding: 0.375rem 0.75rem;
+      font-size: 16px;
+      box-shadow: none;
+      border-radius: 0px;
+      line-height: 1.5;
+      text-transform: none;
+    }
+
+    ::part(button-disabled) {
+      opacity: 0.5;
+    }
+
+    ::part(input) {
+      border-color: #555;
+      border-width: 1px;
+      border-bottom-width: 1px;
+      border-left-width: 1px;
+      border-right-width: 1px;
+      border-top-width: 1px;
+      border-radius: 0;
+      border-style: solid;
+      box-shadow: none;
+      font-size: 1rem;
+      font-weight: normal;
+      line-height: 1.5;
+      padding: 0.375rem 0.75rem;
+    }
+
+    ::part(input-focused) {
+      border-color: #333;
+      box-shadow: 0 0 0 0.25rem rgba(0, 0, 0, 0.25);
+    }
+
+    ::part(input-invalid) {
+      border-color: #8a2a35;
+      box-shadow: 0 0 0 0.25rem rgba(244, 67, 54, 0.25);
+    }
+
+    ::part(input-invalid-and-focused) {
+      box-shadow: 0 0 0 0.25rem rgba(244, 67, 54, 0.25);
+      border-color: #8a2a35;
+    }
+
+    ::part(button-primary) {
+      color: #333;
+      background-color: transparent;
+      border-color: #333;
+    }
+
+    ::part(button-primary):hover {
+      background-color: rgba(0, 0, 0, .05);
+      border-color: #333;
+      color: #333;
+    }
+    </style>
+</head>
+
+<body>
+  <justifi-refund-payment
+    payment-id="payment_123"
+    account-id="acc_123"
+    auth-token="web-component-token"
+    hide-submit-button="true"
+  />
+
+  <!-- Optional external button - this is only needed if the built in button is hidden via the hide-submit-button prop
+   and the refund is submitted via provided refundPayment() method - see below. -->
+  <button id="submit-refund-button">Submit Refund</button>
+</body>
+
+<script>
+  (function () {
+    var refundForm = document.querySelector("justifi-refund-payment");
+
+    refundForm.addEventListener("submit-event", (event) => {
+      /* this event is raised when the server response is received */
+      console.log("server response received", event.detail.response);
+    });
+
+    refundForm.addEventListener("error-event", (event) => {
+      /* here is where you would handle the error */
+      console.error('error-event', event.detail);
+    });
+
+    /* manually call Refund with provided method, if built-in submit button is hidden */
+    document.getElementById("submit-refund-button").addEventListener("click", async () => {
+      const refundData = await refundForm.refundPayment();
+      console.log('Refund data', refundData);
+    });
+  })();
+</script>
+</html>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description:
+        'Ensures refunds are scoped to the correct platform account.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `write:refunds` scope.',
+    },
+    {
+      name: 'payment-id',
+      type: 'string',
+      required: true,
+      description: 'Payment being refunded.',
+    },
+    {
+      name: 'max-amount',
+      type: 'string | number',
+      description:
+        'Upper limit for partial refunds (defaults to remaining amount).',
+    },
+    {
+      name: 'default-reason',
+      type: 'string',
+      description: 'Preselects a refund reason code.',
+    },
+  ]) }} />
+
+### Events
+
+- `submitted`: Emits when the refund is created; payload includes `refund_id` and amount.
+- `error-event`: Fires when validation or network calls fail.
+
+### Public methods
+
+1. `submit()` – Trigger the refund flow (useful if the component is inside a modal with custom buttons).
+2. `focus()` – Move focus to the amount input.
+
+## Theming & Layout
+
+<div dangerouslySetInnerHTML={{ __html: PartsTable([
+    {
+      name: 'font-family',
+      description: 'Controls the font family for the component.',
+    },
+    {
+      name: 'color',
+      description: 'Controls the text color.',
+    },
+    {
+      name: 'background-color',
+      description: 'Controls the background color.',
+    },
+    {
+      name: 'button',
+      description: 'Button styles.',
+    },
+    {
+      name: 'button-disabled',
+      description: 'Disabled button styles.',
+    },
+    {
+      name: 'input',
+      description: 'Input field styles.',
+    },
+    {
+      name: 'input-focused',
+      description: 'Input styles when focused.',
+    },
+    {
+      name: 'input-invalid',
+      description: 'Input styles when invalid.',
+    },
+    {
+      name: 'input-invalid-and-focused',
+      description: 'Input styles when invalid and focused.',
+    },
+    {
+      name: 'button-primary',
+      description: 'Primary button styles.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Programmatic refunds
+
+<pre><code className="language-js">{`const component = document.querySelector('justifi-refund-payment');
+
+document.querySelector('#confirm-refund').onclick = () => component.submit();`}</code></pre>

package/docs/payment-facilitation/tokenize-payment-method/index.mdx

@@ -0,0 +1,361 @@
+---
+id: payment-facilitation/tokenize-payment-method/index
+title: Tokenize Payment Method
+description: Secure standalone card/bank tokenization form with built-in validation and iframe isolation.
+sidebar_position: 1
+---
+
+import { PropsTable, PartsTable, getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render an entire form including a switch to use a credit card or bank account, a submit button and all fields required for proper use. This component can be used standalone or as part of the modular checkout system.
+
+## Usage
+
+<pre><code className="language-html">{`<!DOCTYPE html>
+<html dir="ltr" lang="en">
+
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
+  <title>justifi-tokenize-payment-method</title>
+
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.esm.js"></script>
+  <script nomodule src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.js"></script>
+  <style>
+    ::part(font-family) {
+      font-family: georgia;
+    }
+
+    ::part(color) {
+      color: darkslategray;
+    }
+
+    ::part(background-color) {
+      background-color: transparent;
+    }
+
+    ::part(button) {
+      padding: 0.375rem 0.75rem;
+      font-size: 16px;
+      box-shadow: none;
+      border-radius: 0px;
+      line-height: 1.5;
+      text-transform: none;
+    }
+
+    ::part(button-disabled) {
+      opacity: 0.5;
+    }
+
+    ::part(input) {
+      border-color: #555;
+      border-width: 1px;
+      border-bottom-width: 1px;
+      border-left-width: 1px;
+      border-right-width: 1px;
+      border-top-width: 1px;
+      border-radius: 0;
+      border-style: solid;
+      box-shadow: none;
+      font-size: 1rem;
+      font-weight: normal;
+      line-height: 1.5;
+      padding: 0.375rem 0.75rem;
+    }
+
+    ::part(input-focused) {
+      border-color: #333;
+      box-shadow: 0 0 0 0.25rem rgba(0, 0, 0, 0.25);
+    }
+
+    ::part(input-invalid) {
+      border-color: #8a2a35;
+      box-shadow: 0 0 0 0.25rem rgba(244, 67, 54, 0.25);
+    }
+
+    ::part(input-invalid-and-focused) {
+      box-shadow: 0 0 0 0.25rem rgba(244, 67, 54, 0.25);
+      border-color: #8a2a35;
+    }
+
+    ::part(input-radio) {
+      background-color: #fff;
+      border-color: #333;
+    }
+
+    ::part(input-checkbox) {
+      border-color: #333;
+    }
+    
+    ::part(input-checkbox-checked) {
+      background-color: #000;
+      border-color: #333;
+    }
+
+    ::part(input-checkbox-checked-focused) {
+      background-color: #000;
+      box-shadow: 0 0 0 0.25rem rgba(0, 0, 0, 0.25);
+    }
+
+    ::part(input-checkbox-focused) {
+      background-color: #fff;
+      box-shadow: 0 0 0 0.25rem rgba(0, 0, 0, 0.25);
+    }
+
+    ::part(button-primary) {
+      color: #333;
+      background-color: transparent;
+      border-color: #333;
+    }
+
+    ::part(button-primary):hover {
+      background-color: rgba(0, 0, 0, .05);
+      border-color: #333;
+      color: #333;
+    }
+
+    ::part(radio-list-item) {
+      border-bottom: 1px solid #ddd;
+    }
+    
+    ::part(radio-list-item):hover {
+      background-color: #f9f9f9;
+      cursor: pointer;
+    }
+    </style>
+</head>
+
+  <body>
+    <justifi-tokenize-payment-method
+      account-id="acc_123"
+      auth-token="authToken"
+      payment-method-group-id="pmg_123"
+      submit-button-text="Tokenize Payment Method"
+    />
+  </body>
+
+  <script>
+    const justifiTokenizePaymentMethod = document.querySelector("justifi-tokenize-payment-method");
+
+    // Handle successful tokenization
+    justifiTokenizePaymentMethod.addEventListener("submit-event", (event) => {
+      const response = event.detail.response;
+      console.log("Tokenization successful:", response);
+      
+      if (response.token) {
+        console.log("Payment method token:", response.token);
+      }
+      
+      if (response.data) {
+        console.log("Full payment method data:", response.data);
+      }
+    });
+
+    // Handle errors
+    justifiTokenizePaymentMethod.addEventListener("error-event", (event) => {
+      console.error("Tokenization error:", event.detail);
+    });
+
+    // External tokenize button (when built-in submit button is hidden)
+    document.getElementById("tokenize-button").addEventListener("click", async () => {
+      try {
+        const result = await justifiTokenizePaymentMethod.tokenizePaymentMethod();
+        console.log("External tokenization result:", result);
+      } catch (error) {
+        console.error("External tokenization failed:", error);
+      }
+    });
+
+    // Fill billing form programmatically
+    document.getElementById("fill-billing-form").addEventListener("click", async () => {
+      await justifiTokenizePaymentMethod.fillBillingForm({
+        name: "John Doe",
+        address_line1: "123 Main St",
+        address_line2: "Apt 1",
+        address_city: "Anytown",
+        address_state: "NY", // Use 2-letter state code
+        address_postal_code: "12345",
+      });
+      console.log("Billing form filled");
+    }); 
+
+    // Validate form
+    document.getElementById("validate-form").addEventListener("click", async () => {
+      const validation = await justifiTokenizePaymentMethod.validate();
+      console.log("Validation result:", validation);
+      
+      if (validation.isValid) {
+        console.log("Form is valid!");
+      } else {
+        console.log("Form has errors:", validation.errors);
+      }
+    });
+
+  </script>
+
+</html>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description:
+        'Platform account that will own the resulting payment method.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description:
+        'Short-lived Web Component Token with `write:tokenize:account_id` scope.',
+    },
+    {
+      name: 'payment-method-group-id',
+      type: 'string',
+      description:
+        'Optional grouping identifier that lets you preselect payment rails in Modular Checkout.',
+    },
+    {
+      name: 'hide-submit-button',
+      type: 'boolean',
+      defaultValue: 'false',
+      description:
+        'Hides the internal CTA when hosting app handles submission.',
+    },
+    {
+      name: 'save-payment-method-label',
+      type: 'string',
+      description:
+        'Overrides the checkbox label when allowing customers to store a card.',
+    },
+    {
+      name: 'locale',
+      type: 'string',
+      defaultValue: 'en-US',
+      description:
+        'Controls localization of labels, placeholders, and currency formatting.',
+    },
+    {
+      name: 'theme',
+      type: 'string',
+      description: 'Name of a predefined theme exported by JustiFi (optional).',
+    },
+  ]) }} />
+
+### Events
+
+- `tokenized`: fires when a payment token is created; payload includes `payment_method_token` and metadata.
+- `error`: fires if tokenization fails; payload includes `code`, `message`, and validation hints.
+
+### Public methods
+
+1. `tokenizePaymentMethod()` – programmatically trigger submission (returns a promise that resolves to a token payload).
+2. `fillBillingForm(partialBillingDetails)` – prefill customers' billing information from saved data.
+
+## Theming & Layout
+
+- Hosted fields remain inside PCI-safe iframes, so styling focuses on the outer wrapper plus the `::part` hooks listed below.
+
+<div dangerouslySetInnerHTML={{ __html: PartsTable([
+    {
+      name: 'font-family',
+      description: 'Controls the font family for the component.',
+    },
+    {
+      name: 'color',
+      description: 'Controls the text color.',
+    },
+    {
+      name: 'background-color',
+      description: 'Controls the background color.',
+    },
+    {
+      name: 'button',
+      description: 'Button styles.',
+    },
+    {
+      name: 'button-disabled',
+      description: 'Disabled button styles.',
+    },
+    {
+      name: 'input',
+      description: 'Input field styles.',
+    },
+    {
+      name: 'input-focused',
+      description: 'Input styles when focused.',
+    },
+    {
+      name: 'input-invalid',
+      description: 'Input styles when invalid.',
+    },
+    {
+      name: 'input-invalid-and-focused',
+      description: 'Input styles when invalid and focused.',
+    },
+    {
+      name: 'input-radio',
+      description: 'Radio input styles.',
+    },
+    {
+      name: 'input-checkbox',
+      description: 'Checkbox input styles.',
+    },
+    {
+      name: 'input-checkbox-checked',
+      description: 'Checkbox input styles when checked.',
+    },
+    {
+      name: 'input-checkbox-checked-focused',
+      description: 'Checkbox input styles when checked and focused.',
+    },
+    {
+      name: 'input-checkbox-focused',
+      description: 'Checkbox input styles when focused.',
+    },
+    {
+      name: 'button-primary',
+      description: 'Primary button styles.',
+    },
+    {
+      name: 'radio-list-item',
+      description: 'Radio list item styles.',
+    },
+  ]) }} />
+
+- Slots are not exposed (all inputs are encapsulated in PCI iframes), so styling relies on CSS variables and `::part` hooks for wrapper elements.
+
+## Static examples
+
+### External submission control
+
+Hide the internal CTA and trigger tokenization manually (e.g., to combine with a review step).
+
+<pre><code className="language-html">{`<justifi-tokenize-payment-method
+  account-id="acc_123"
+  auth-token="wct_abc123"
+  hide-submit-button
+  ref={el => (window.tokenizer = el)}
+/>
+
+<button onclick="window.tokenizer.tokenizePaymentMethod()">
+  Submit Payment
+</button>
+`}</code></pre>
+
+### Prefill billing info
+
+<pre><code className="language-js">{`const tokenizer = document.querySelector('justifi-tokenize-payment-method');
+
+tokenizer.fillBillingForm({
+name: 'Leslie Knope',
+address_line1: '123 Main St',
+address_city: 'Pawnee',
+address_state: 'IN',
+address_postal_code: '47998',
+});`}</code></pre>