npm - @justifi/webcomponents - Versions diffs - 6.7.0 → 6.7.2 - Mend

@justifi/webcomponents 6.7.0 → 6.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (167) hide show

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

@@ -0,0 +1,241 @@
+---
+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.',
+      },
+    ]),
+  }}
+/>

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

@@ -0,0 +1,350 @@
+---
+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.