@lightspeed/online-payments-sdk 1.7.1 → 1.7.3

package/README.md

@@ -1,6 +1,11 @@
 # Lightspeed Online Payments SDK
 
-`@lightspeed/online-payments-sdk` is a browser SDK for mounting Lightspeed Payments widgets (Stripe and Adyen) in web applications.
+`@lightspeed/online-payments-sdk` is a browser SDK for displaying Lightspeed Payments widgets in your web application.
+
+This is intended for partners who wish to add payments functionality to an integration with a Lightspeed product.
+
+For onboarding questions, account configuration, or production enablement: contact your Lightspeed
+representative.
 
 ## Installation
 
@@ -8,94 +13,123 @@
 npm install @lightspeed/online-payments-sdk
 ```
 
-## Quick start
-
-```ts
-import {LightspeedPayments} from '@lightspeed/online-payments-sdk';
-
-const controller = await LightspeedPayments.v1.mountPaymentWidget(sessionToken, {
-  mountPoint: document.getElementById('payment-widget')!,
-});
+## Requirements
 
-controller.unmount();
-```
+- A browser environment with `window` and `document`
+- A payment session obtained from your Lightspeed Payments integration
+- An HTML element where the payment widget can be mounted
 
-## Compatibility
-
-- TypeScript/JavaScript
-- Browser runtime (requires `window`)
-
-## Theming
+## Quick start
 
-The SDK supports custom themes. If no theme is specified, Stripe defaults are used.
+Add a mount element to your page:
 
-### Available themes
+```html
+<div id="payment-widget"></div>
+```
 
-- default (no `theme` value)
-- `invoicing`
-- `dark`
+Mount the widget with the payment session from your integration:
 
 ```ts
 import {LightspeedPayments} from '@lightspeed/online-payments-sdk';
 
-await LightspeedPayments.v1.mountPaymentWidget(paymentSession, {
-  mountPoint: document.getElementById('payment-widget')!,
-  theme: 'dark',
+const mountPoint = document.getElementById('payment-widget');
+
+if (!mountPoint) {
+  throw new Error('Payment widget mount point was not found');
+}
+
+const controller = await LightspeedPayments.v1.mountPaymentWidget(session, {
+  mountPoint,
 });
 ```
 
-### Container styling
+Keep the returned controller to submit the widget or remove it when the containing page or component is no longer needed.
+
+## Configuration
 
-For dark mode, the SDK styles the mount element you pass in `mountPoint`. If you style a parent wrapper, use `THEME_COLORS`.
+`mountPaymentWidget(session, configuration)` accepts a payment session and the following configuration:
+
+| Option          | Description                                                      |
+| --------------- | ---------------------------------------------------------------- |
+| `mountPoint`    | Required `HTMLElement` where the SDK renders the payment widget. |
+| `defaultValues` | Optional initial address values: `country` and `postalCode`.     |
+| `listeners`     | Optional callbacks for widget lifecycle and payment events.      |
+| `theme`         | Optional visual theme: `dark`.                                   |
 
 ```ts
-import {THEME_COLORS} from '@lightspeed/online-payments-sdk';
+const controller = await LightspeedPayments.v1.mountPaymentWidget(session, {
+  mountPoint,
+  defaultValues: {
+    country: 'CA',
+    postalCode: 'H1H1H1',
+  },
+  listeners: {
+    onReady: () => {
+      // The widget is ready for payer input.
+    },
+    onChange: event => {
+      submitButton.disabled = event.code !== 'Complete';
+    },
+    onSucceeded: () => {
+      // Continue after a successful payment or payment-method save.
+    },
+    onDeclined: event => {
+      // Show a decline message appropriate for event.code.
+    },
+    onError: event => {
+      // Handle a widget or processing error.
+    },
+  },
+});
 ```
 
-## Documentation
+### Events
 
-- Datadog logging reference: `packages/lsp-online-payments-sdk/docs/DATADOG_LOGGING.md`
-- Sandbox releases (testing unreleased builds in a real app): `packages/lsp-online-payments-sdk/docs/sandbox-releases.md`
+Listeners receive an event with a `status` and `code`. Available listener names are `onReady`, `onChange`, `onSucceeded`, `onPending`, `onDeclined`, and `onError`.
 
-## Development
+| Status      | Codes                                                                                                          |
+| ----------- | -------------------------------------------------------------------------------------------------------------- |
+| `Ready`     | `Ready`                                                                                                        |
+| `Change`    | `Complete`, `Incomplete`                                                                                       |
+| `Succeeded` | `Authorized`                                                                                                   |
+| `Pending`   | `Processing`                                                                                                   |
+| `Declined`  | `CardValidation`, `Generic`, `PaymentMethodNotSupported`                                                       |
+| `Error`     | `Unexpected`, `InvalidSession`, `InvalidSessionPayload`, `UnsupportedLocation`, `Processing`, `FormValidation` |
 
-Run SDK checks (same order as CI):
+## Submit and unmount
 
-```sh
-npm run lint --workspace @lightspeed/online-payments-sdk
-npm run typecheck --workspace @lightspeed/online-payments-sdk
-npm run test --workspace @lightspeed/online-payments-sdk
-```
+Call `submit()` in response to your application's payment action. Call `unmount()` before removing or replacing the mount element.
 
-Build package:
+```ts
+submitButton.addEventListener('click', async () => {
+  await controller.submit();
+});
 
-```sh
-npm run build --workspace @lightspeed/online-payments-sdk
+// For example, during page or component cleanup.
+controller.unmount();
 ```
 
-Inspect publish contents:
+## Theming
 
-```sh
-npm pack --dry-run
-```
+Use `theme` to select a widget appearance:
 
-## Publishing and release flow
+- Omit `theme` to use the default appearance.
+- `dark` uses a dark appearance and styles the mount element with a dark background.
 
-Publishing is handled by CircleCI (not manual local publish).
+Custom themes can be used with support from the Lightspeed Payments team.
 
-- Release path runs on `main` and `release/*`.
-- CircleCI runs quality gates (`lint`, `typecheck`, unit tests, build, e2e).
-- `verify_package_version` compares local `package.json` version with npm.
-- If local version is not higher, publish is skipped.
-- If local version is higher, the workflow pauses at manual approval (`pause_workflow`).
-- A human must approve before the `release` job runs `npm publish`.
+```ts
+await LightspeedPayments.v1.mountPaymentWidget(session, {
+  mountPoint,
+  theme: 'dark',
+});
+```
 
-In practice: bump `version` in `packages/lsp-online-payments-sdk/package.json`, merge to `main`, then approve the release hold in CircleCI.
+For a wrapper around a widget using the `dark` theme, use `THEME_COLORS` to match the SDK's dark container colors:
 
-### Sandbox releases
+```ts
+import {THEME_COLORS} from '@lightspeed/online-payments-sdk';
 
-To test unreleased SDK changes inside a real app without touching the production
-package on public npm, publish a **sandbox** build to GitHub Packages: push a
-`sandbox/*` branch and approve the `hold_sandbox` step in CircleCI. Consuming an
-app requires no `import` changes — just an `.npmrc` scope + a `package.json`
-alias. See `docs/sandbox-releases.md` for the full publish and consume steps.
+wrapper.style.backgroundColor = THEME_COLORS.DARK.BACKGROUND;
+wrapper.style.color = THEME_COLORS.DARK.TEXT;
+```

package/dist/cjs/v1/stripe/partnerProduct.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Helpers for identifying partner-initiated sessions from the session
+ * metadata `product` value.
+ *
+ * The processing service encodes the product as
+ * `partner:{grantor}::{applicationId}` for integrator (partner) sessions
+ * (see `formatPartnerProductValue` in lsp-processing-service). We only need to
+ * read the grantor segment here to branch on partner-specific behavior such as
+ * custom card consent text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPartnerGrantor = getPartnerGrantor;
+var PARTNER_PRODUCT_PREFIX = 'partner:';
+var PARTNER_PRODUCT_SEGMENT_SEPARATOR = '::';
+/**
+ * Parse the grantor segment out of a partner product value.
+ * Returns `undefined` for non-partner or malformed product values.
+ */
+function getPartnerGrantor(product) {
+    if (typeof product !== 'string') {
+        return undefined;
+    }
+    if (!product.startsWith(PARTNER_PRODUCT_PREFIX)) {
+        return undefined;
+    }
+    var suffix = product.slice(PARTNER_PRODUCT_PREFIX.length);
+    var separatorIndex = suffix.indexOf(PARTNER_PRODUCT_SEGMENT_SEPARATOR);
+    if (separatorIndex <= 0) {
+        return undefined;
+    }
+    var grantor = suffix.slice(0, separatorIndex);
+    var applicationId = suffix.slice(separatorIndex + PARTNER_PRODUCT_SEGMENT_SEPARATOR.length);
+    // Require both segments: `partner:golf::` (empty applicationId) is malformed.
+    if (grantor.length === 0 || applicationId.length === 0) {
+        return undefined;
+    }
+    return grantor;
+}

package/dist/cjs/v1/stripe/shared.js

@@ -50,6 +50,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.initStripe = initStripe;
 exports.createPaymentElementOptions = createPaymentElementOptions;
 exports.createAddressElementOptions = createAddressElementOptions;
+exports.buildCardConsentText = buildCardConsentText;
+exports.createCardConsentElement = createCardConsentElement;
 exports.createPaymentElement = createPaymentElement;
 exports.setupChangeEventHandler = setupChangeEventHandler;
 exports.createAddressElement = createAddressElement;
@@ -93,11 +95,10 @@ function initStripe(context, theme) {
  * @param theme - Theme configuration
  * @param hideNameField - Whether to hide the billing details name field (used when address element is present to avoid duplicates with ACH)
  * @param businessName - Overrides the merchant name Stripe renders in mandate text (passed to `business.name`)
- * @param showCardMandate - Forces Stripe to render its card mandate text (which includes `business.name`). Used for partner payment-with-save flows where Stripe would otherwise not show terms.
+ * @param cardMandate - Maps directly to Stripe's `terms.card`: `'always'` forces Stripe's card mandate (with `business.name`), `'never'` hides it (used when the SDK renders its own consent text). Omit to leave Stripe's `'auto'` default.
  */
-function createPaymentElementOptions(defaultValues, theme, hideNameField, businessName, showCardMandate) {
+function createPaymentElementOptions(defaultValues, theme, hideNameField, businessName, cardMandate) {
     if (hideNameField === void 0) { hideNameField = false; }
-    if (showCardMandate === void 0) { showCardMandate = false; }
     var options = __assign(__assign(__assign({ wallets: {
             applePay: 'never',
             googlePay: 'never',
@@ -108,7 +109,7 @@ function createPaymentElementOptions(defaultValues, theme, hideNameField, busine
                 name: 'never', // prevent duplicate Name field on the form when using ACH (only when address element is present)
             },
         },
-    })), { terms: __assign({ usBankAccount: 'never' }, (showCardMandate && businessName && { card: 'always' })) }), (businessName && { business: { name: businessName } }));
+    })), { terms: __assign({ usBankAccount: 'never' }, (cardMandate && { card: cardMandate })) }), (businessName && { business: { name: businessName } }));
     if (defaultValues) {
         options.defaultValues = {
             billingDetails: {
@@ -186,6 +187,39 @@ function createCustomTermsElement() {
     }
     return termsContainer;
 }
+/**
+ * Build a card consent sentence by interpolating the business name and reason
+ * into the flow-specific template.
+ * @param variant - 'mandatory' for the save-card flow (consent by providing card
+ *   details), 'checkbox' for the pay-and-save flow (consent by checking the box).
+ */
+function buildCardConsentText(businessName, reason, variant) {
+    var template = variant === 'checkbox'
+        ? terms_1.PARTNER_CARD_CONSENT_TEXT.CHECKBOX_TEMPLATE
+        : terms_1.PARTNER_CARD_CONSENT_TEXT.MANDATORY_TEMPLATE;
+    return template
+        .replace(/\{business\}/g, function () { return businessName; })
+        .replace(/\{reason\}/g, function () { return reason; });
+}
+/**
+ * Render a card consent element that replaces Stripe's built-in card mandate
+ * (suppressed via `terms.card: 'never'`) with the given copy. Pure render
+ * primitive — the caller composes the sentence (e.g. via `buildCardConsentText`)
+ * so this makes no assumption about the wording. Uses dedicated
+ * `.stripe-card-consent-*` classes whose styling mirrors the ACH custom-terms
+ * text.
+ */
+function createCardConsentElement(consentText) {
+    var container = document.createElement('div');
+    container.className = 'stripe-card-consent-container';
+    var text = document.createElement('p');
+    text.className = 'stripe-card-consent-text';
+    // Plain text (no links) — use textContent to avoid injecting the composed
+    // business name as HTML.
+    text.textContent = consentText;
+    container.appendChild(text);
+    return container;
+}
 /**
  * Create and mount payment element
  */
@@ -285,7 +319,7 @@ function createAddressElement(elements, options, mountElement) {
 /**
  * Clean up elements and containers
  */
-function cleanupElements(paymentElement, addressElement, paymentContainer, addressContainer, customTermsContainer) {
+function cleanupElements(paymentElement, addressElement, paymentContainer, addressContainer, customTermsContainer, cardConsentContainer) {
     paymentElement.unmount();
     if (addressElement) {
         addressElement.unmount();
@@ -300,6 +334,9 @@ function cleanupElements(paymentElement, addressElement, paymentContainer, addre
     if (customTermsContainer) {
         customTermsContainer.remove();
     }
+    if (cardConsentContainer) {
+        cardConsentContainer.remove();
+    }
 }
 /**
  * Handle save card operation

package/dist/cjs/v1/stripe/terms.js

@@ -8,7 +8,8 @@
  * - Replace with translated versions based on locale
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACH_TERMS_URL = exports.ACH_TERMS_TEXT = void 0;
+exports.ACH_TERMS_URL = exports.PARTNER_CARD_CONSENT_TEXT = exports.ACH_TERMS_TEXT = void 0;
+exports.getPartnerCardConsentReason = getPartnerCardConsentReason;
 exports.ACH_TERMS_TEXT = {
     /**
      * Main terms text displayed for US Bank Account payments.
@@ -37,6 +38,45 @@ exports.ACH_TERMS_TEXT = {
     EXPANDED_TERMS_PRIVACY_PREFIX: 'Lightspeed may collect or access certain payment-related information as described in the platform agreement and',
     PRIVACY_POLICY_LINK_TEXT: 'Privacy Policy',
 };
+/**
+ * Partner card consent text — replaces Stripe's built-in card mandate (whose
+ * wording is fixed by Stripe and cannot be customized) with copy the SDK renders
+ * itself for partner card payments. `{business}` and `{reason}` are interpolated
+ * at render time (reason supplied by the caller, e.g. via
+ * `getPartnerCardConsentReason`).
+ *
+ * NOTE: The SDK does not translate these strings at runtime — they render in
+ * English regardless of the session `locale` (which only localizes Stripe's own
+ * Element UI). Like the ACH strings above, they are kept as plain constants so
+ * they *could* be extracted for Transifex later, but no runtime i18n exists
+ * today.
+ */
+exports.PARTNER_CARD_CONSENT_TEXT = {
+    // save-card flow: consent given by providing card details.
+    MANDATORY_TEMPLATE: 'By providing your card information, you authorize {business} to charge your card for {reason} in accordance with their terms.',
+    // pay-and-save flow: consent tied to the save checkbox.
+    CHECKBOX_TEMPLATE: 'By checking the box above, you authorize {business} to charge your card for {reason} in accordance with their terms.',
+};
+/**
+ * Consent reason per partner grantor — what the saved card may be charged for,
+ * keyed by the grantor segment of the product (`partner:{grantor}::...`). Add an
+ * entry to offer custom card consent to another partner. Hardcoded for now; may
+ * become a per-session input from Processing Service later.
+ */
+var PARTNER_CARD_CONSENT_REASONS = {
+    golf: 'future payments towards charges related to tee-time bookings and/or house accounts as applicable',
+};
+/**
+ * The configured consent reason for a partner grantor, or `undefined` if the
+ * partner has none (in which case no custom card consent is rendered).
+ */
+function getPartnerCardConsentReason(grantor) {
+    if (grantor &&
+        Object.prototype.hasOwnProperty.call(PARTNER_CARD_CONSENT_REASONS, grantor)) {
+        return PARTNER_CARD_CONSENT_REASONS[grantor];
+    }
+    return undefined;
+}
 exports.ACH_TERMS_URL = {
     STRIPE_ACH_AUTHORIZATION: 'https://stripe.com/legal/ach-payments/authorization',
     PRIVACY_POLICY: 'https://www.lightspeedhq.com/legal/privacy-policy/',

package/dist/cjs/v1/stripe/widgets/moto.js

@@ -38,25 +38,39 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mountMotoWidget = mountMotoWidget;
 var shared_1 = require("../shared");
+var partnerProduct_1 = require("../partnerProduct");
+var terms_1 = require("../terms");
 /**
  * Mount MOTO widget for moto and moto-with-save session types
  * MOTO (Mail Order/Telephone Order) forms don't require address collection
  */
 function mountMotoWidget(mountElement, session, eventBroadcaster, defaultValues, theme) {
     return __awaiter(this, void 0, void 0, function () {
-        var _a, stripe, elements, paymentOptions, _b, paymentElement, paymentContainer, customTermsContainer;
+        var _a, stripe, elements, businessName, consentReason, renderPartnerConsent, cardMandate, paymentOptions, _b, paymentElement, paymentContainer, customTermsContainer, cardConsentContainer;
         return __generator(this, function (_c) {
             switch (_c.label) {
                 case 0: return [4 /*yield*/, (0, shared_1.initStripe)(session.context, theme)];
                 case 1:
                     _a = _c.sent(), stripe = _a.stripe, elements = _a.elements;
-                    paymentOptions = (0, shared_1.createPaymentElementOptions)(defaultValues, theme, false, session.context.businessName);
+                    businessName = session.context.businessName;
+                    consentReason = (0, terms_1.getPartnerCardConsentReason)((0, partnerProduct_1.getPartnerGrantor)(session.metadata.product));
+                    renderPartnerConsent = session.metadata.sessionType === 'save' &&
+                        !!businessName &&
+                        !!consentReason;
+                    cardMandate = renderPartnerConsent
+                        ? 'never'
+                        : undefined;
+                    paymentOptions = (0, shared_1.createPaymentElementOptions)(defaultValues, theme, false, businessName, cardMandate);
                     _b = (0, shared_1.createPaymentElement)(elements, paymentOptions, mountElement, eventBroadcaster), paymentElement = _b.element, paymentContainer = _b.container, customTermsContainer = _b.customTermsContainer;
+                    if (renderPartnerConsent) {
+                        cardConsentContainer = (0, shared_1.createCardConsentElement)((0, shared_1.buildCardConsentText)(businessName, consentReason, 'mandatory'));
+                        mountElement.appendChild(cardConsentContainer);
+                    }
                     // Setup change handler for payment element only (MOTO forms don't have address element)
                     (0, shared_1.setupChangeEventHandler)(paymentElement, eventBroadcaster);
                     return [2 /*return*/, {
                             unmount: function () {
-                                (0, shared_1.cleanupElements)(paymentElement, null, paymentContainer, null, customTermsContainer);
+                                (0, shared_1.cleanupElements)(paymentElement, null, paymentContainer, null, customTermsContainer, cardConsentContainer);
                             },
                             submit: (0, shared_1.createSubmitHandler)(stripe, elements, session, eventBroadcaster, null),
                         }];

package/dist/cjs/v1/stripe/widgets/payment.js

@@ -38,17 +38,21 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mountPaymentWidget = mountPaymentWidget;
 var shared_1 = require("../shared");
+var partnerProduct_1 = require("../partnerProduct");
+var terms_1 = require("../terms");
 /**
  * Mount payment widget for payment and payment-with-save session types
  */
 function mountPaymentWidget(mountElement, session, eventBroadcaster, defaultValues, theme) {
     return __awaiter(this, void 0, void 0, function () {
-        var _a, stripe, elements, productMetadata, isPartnerProduct, addressElement, addressContainer, addressOptions, created, showCardMandate, paymentOptions, _b, paymentElement, paymentContainer, customTermsContainer;
+        var _a, stripe, elements, businessName, isPayWithSave, productMetadata, isPartnerProduct, addressElement, addressContainer, addressOptions, created, consentReason, renderPartnerConsent, cardMandate, paymentOptions, _b, paymentElement, paymentContainer, customTermsContainer, cardConsentContainer;
         return __generator(this, function (_c) {
             switch (_c.label) {
                 case 0: return [4 /*yield*/, (0, shared_1.initStripe)(session.context, theme)];
                 case 1:
                     _a = _c.sent(), stripe = _a.stripe, elements = _a.elements;
+                    businessName = session.context.businessName;
+                    isPayWithSave = session.metadata.sessionType === 'payment-with-save';
                     productMetadata = session.metadata.product;
                     isPartnerProduct = typeof productMetadata === 'string' &&
                         productMetadata.startsWith('partner:');
@@ -60,16 +64,24 @@ function mountPaymentWidget(mountElement, session, eventBroadcaster, defaultValu
                         addressElement = created.element;
                         addressContainer = created.container;
                     }
-                    showCardMandate = session.metadata.sessionType === 'payment-with-save' &&
-                        !!session.context.businessName &&
-                        isPartnerProduct;
-                    paymentOptions = (0, shared_1.createPaymentElementOptions)(defaultValues, theme, !!addressElement, session.context.businessName, showCardMandate);
+                    consentReason = (0, terms_1.getPartnerCardConsentReason)((0, partnerProduct_1.getPartnerGrantor)(productMetadata));
+                    renderPartnerConsent = isPayWithSave && !!businessName && !!consentReason;
+                    cardMandate = renderPartnerConsent
+                        ? 'never'
+                        : isPayWithSave && !!businessName && isPartnerProduct
+                            ? 'always'
+                            : undefined;
+                    paymentOptions = (0, shared_1.createPaymentElementOptions)(defaultValues, theme, !!addressElement, businessName, cardMandate);
                     _b = (0, shared_1.createPaymentElement)(elements, paymentOptions, mountElement, eventBroadcaster), paymentElement = _b.element, paymentContainer = _b.container, customTermsContainer = _b.customTermsContainer;
+                    if (renderPartnerConsent) {
+                        cardConsentContainer = (0, shared_1.createCardConsentElement)((0, shared_1.buildCardConsentText)(businessName, consentReason, 'checkbox'));
+                        mountElement.appendChild(cardConsentContainer);
+                    }
                     // Setup change handler that emits Complete only when both elements are complete
                     (0, shared_1.setupChangeEventHandler)(paymentElement, eventBroadcaster, addressElement);
                     return [2 /*return*/, {
                             unmount: function () {
-                                (0, shared_1.cleanupElements)(paymentElement, addressElement, paymentContainer, addressContainer, customTermsContainer);
+                                (0, shared_1.cleanupElements)(paymentElement, addressElement, paymentContainer, addressContainer, customTermsContainer, cardConsentContainer);
                             },
                             submit: (0, shared_1.createSubmitHandler)(stripe, elements, session, eventBroadcaster, addressElement),
                         }];

package/dist/cjs/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
 // This file is auto-generated during the build process
 // DO NOT EDIT MANUALLY - Version is extracted from package.json
-exports.SDK_VERSION = '1.7.1';
+exports.SDK_VERSION = '1.7.3';

package/dist/v1/stripe/partnerProduct.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Helpers for identifying partner-initiated sessions from the session
+ * metadata `product` value.
+ *
+ * The processing service encodes the product as
+ * `partner:{grantor}::{applicationId}` for integrator (partner) sessions
+ * (see `formatPartnerProductValue` in lsp-processing-service). We only need to
+ * read the grantor segment here to branch on partner-specific behavior such as
+ * custom card consent text.
+ */
+/**
+ * Parse the grantor segment out of a partner product value.
+ * Returns `undefined` for non-partner or malformed product values.
+ */
+export declare function getPartnerGrantor(product?: string): string | undefined;

package/dist/v1/stripe/partnerProduct.js

@@ -0,0 +1,36 @@
+/**
+ * Helpers for identifying partner-initiated sessions from the session
+ * metadata `product` value.
+ *
+ * The processing service encodes the product as
+ * `partner:{grantor}::{applicationId}` for integrator (partner) sessions
+ * (see `formatPartnerProductValue` in lsp-processing-service). We only need to
+ * read the grantor segment here to branch on partner-specific behavior such as
+ * custom card consent text.
+ */
+var PARTNER_PRODUCT_PREFIX = 'partner:';
+var PARTNER_PRODUCT_SEGMENT_SEPARATOR = '::';
+/**
+ * Parse the grantor segment out of a partner product value.
+ * Returns `undefined` for non-partner or malformed product values.
+ */
+export function getPartnerGrantor(product) {
+    if (typeof product !== 'string') {
+        return undefined;
+    }
+    if (!product.startsWith(PARTNER_PRODUCT_PREFIX)) {
+        return undefined;
+    }
+    var suffix = product.slice(PARTNER_PRODUCT_PREFIX.length);
+    var separatorIndex = suffix.indexOf(PARTNER_PRODUCT_SEGMENT_SEPARATOR);
+    if (separatorIndex <= 0) {
+        return undefined;
+    }
+    var grantor = suffix.slice(0, separatorIndex);
+    var applicationId = suffix.slice(separatorIndex + PARTNER_PRODUCT_SEGMENT_SEPARATOR.length);
+    // Require both segments: `partner:golf::` (empty applicationId) is malformed.
+    if (grantor.length === 0 || applicationId.length === 0) {
+        return undefined;
+    }
+    return grantor;
+}

package/dist/v1/stripe/shared.d.ts

@@ -22,13 +22,29 @@ export declare function initStripe(context: StripeContext, theme?: PaymentWidget
  * @param theme - Theme configuration
  * @param hideNameField - Whether to hide the billing details name field (used when address element is present to avoid duplicates with ACH)
  * @param businessName - Overrides the merchant name Stripe renders in mandate text (passed to `business.name`)
- * @param showCardMandate - Forces Stripe to render its card mandate text (which includes `business.name`). Used for partner payment-with-save flows where Stripe would otherwise not show terms.
+ * @param cardMandate - Maps directly to Stripe's `terms.card`: `'always'` forces Stripe's card mandate (with `business.name`), `'never'` hides it (used when the SDK renders its own consent text). Omit to leave Stripe's `'auto'` default.
  */
-export declare function createPaymentElementOptions(defaultValues?: DefaultValues, theme?: PaymentWidgetTheme, hideNameField?: boolean, businessName?: string, showCardMandate?: boolean): StripePaymentElementOptions;
+export declare function createPaymentElementOptions(defaultValues?: DefaultValues, theme?: PaymentWidgetTheme, hideNameField?: boolean, businessName?: string, cardMandate?: 'always' | 'never'): StripePaymentElementOptions;
 /**
  * Create address element options
  */
 export declare function createAddressElementOptions(defaultValues?: DefaultValues): StripeAddressElementOptions;
+/**
+ * Build a card consent sentence by interpolating the business name and reason
+ * into the flow-specific template.
+ * @param variant - 'mandatory' for the save-card flow (consent by providing card
+ *   details), 'checkbox' for the pay-and-save flow (consent by checking the box).
+ */
+export declare function buildCardConsentText(businessName: string, reason: string, variant: 'mandatory' | 'checkbox'): string;
+/**
+ * Render a card consent element that replaces Stripe's built-in card mandate
+ * (suppressed via `terms.card: 'never'`) with the given copy. Pure render
+ * primitive — the caller composes the sentence (e.g. via `buildCardConsentText`)
+ * so this makes no assumption about the wording. Uses dedicated
+ * `.stripe-card-consent-*` classes whose styling mirrors the ACH custom-terms
+ * text.
+ */
+export declare function createCardConsentElement(consentText: string): HTMLElement;
 /**
  * Create and mount payment element
  */
@@ -56,7 +72,7 @@ export declare function createAddressElement(elements: StripeElements, options:
 /**
  * Clean up elements and containers
  */
-export declare function cleanupElements(paymentElement: StripePaymentElement, addressElement: StripeAddressElement | null, paymentContainer: HTMLElement, addressContainer: HTMLElement | null, customTermsContainer?: HTMLElement): void;
+export declare function cleanupElements(paymentElement: StripePaymentElement, addressElement: StripeAddressElement | null, paymentContainer: HTMLElement, addressContainer: HTMLElement | null, customTermsContainer?: HTMLElement, cardConsentContainer?: HTMLElement): void;
 /**
  * Handle save card operation
  */

package/dist/v1/stripe/shared.js

@@ -49,7 +49,7 @@ import { loadStripe, } from '@stripe/stripe-js';
 import { EventBuilder } from './ResultBuilder';
 import { InvalidSessionPayloadError, ProcessingError } from '../error';
 import { getThemeConfig } from './themes';
-import { ACH_TERMS_TEXT, ACH_TERMS_URL } from './terms';
+import { ACH_TERMS_TEXT, ACH_TERMS_URL, PARTNER_CARD_CONSENT_TEXT } from './terms';
 /**
  * Initialize Stripe with the given context
  */
@@ -81,11 +81,10 @@ export function initStripe(context, theme) {
  * @param theme - Theme configuration
  * @param hideNameField - Whether to hide the billing details name field (used when address element is present to avoid duplicates with ACH)
  * @param businessName - Overrides the merchant name Stripe renders in mandate text (passed to `business.name`)
- * @param showCardMandate - Forces Stripe to render its card mandate text (which includes `business.name`). Used for partner payment-with-save flows where Stripe would otherwise not show terms.
+ * @param cardMandate - Maps directly to Stripe's `terms.card`: `'always'` forces Stripe's card mandate (with `business.name`), `'never'` hides it (used when the SDK renders its own consent text). Omit to leave Stripe's `'auto'` default.
  */
-export function createPaymentElementOptions(defaultValues, theme, hideNameField, businessName, showCardMandate) {
+export function createPaymentElementOptions(defaultValues, theme, hideNameField, businessName, cardMandate) {
     if (hideNameField === void 0) { hideNameField = false; }
-    if (showCardMandate === void 0) { showCardMandate = false; }
     var options = __assign(__assign(__assign({ wallets: {
             applePay: 'never',
             googlePay: 'never',
@@ -96,7 +95,7 @@ export function createPaymentElementOptions(defaultValues, theme, hideNameField,
                 name: 'never', // prevent duplicate Name field on the form when using ACH (only when address element is present)
             },
         },
-    })), { terms: __assign({ usBankAccount: 'never' }, (showCardMandate && businessName && { card: 'always' })) }), (businessName && { business: { name: businessName } }));
+    })), { terms: __assign({ usBankAccount: 'never' }, (cardMandate && { card: cardMandate })) }), (businessName && { business: { name: businessName } }));
     if (defaultValues) {
         options.defaultValues = {
             billingDetails: {
@@ -174,6 +173,39 @@ function createCustomTermsElement() {
     }
     return termsContainer;
 }
+/**
+ * Build a card consent sentence by interpolating the business name and reason
+ * into the flow-specific template.
+ * @param variant - 'mandatory' for the save-card flow (consent by providing card
+ *   details), 'checkbox' for the pay-and-save flow (consent by checking the box).
+ */
+export function buildCardConsentText(businessName, reason, variant) {
+    var template = variant === 'checkbox'
+        ? PARTNER_CARD_CONSENT_TEXT.CHECKBOX_TEMPLATE
+        : PARTNER_CARD_CONSENT_TEXT.MANDATORY_TEMPLATE;
+    return template
+        .replace(/\{business\}/g, function () { return businessName; })
+        .replace(/\{reason\}/g, function () { return reason; });
+}
+/**
+ * Render a card consent element that replaces Stripe's built-in card mandate
+ * (suppressed via `terms.card: 'never'`) with the given copy. Pure render
+ * primitive — the caller composes the sentence (e.g. via `buildCardConsentText`)
+ * so this makes no assumption about the wording. Uses dedicated
+ * `.stripe-card-consent-*` classes whose styling mirrors the ACH custom-terms
+ * text.
+ */
+export function createCardConsentElement(consentText) {
+    var container = document.createElement('div');
+    container.className = 'stripe-card-consent-container';
+    var text = document.createElement('p');
+    text.className = 'stripe-card-consent-text';
+    // Plain text (no links) — use textContent to avoid injecting the composed
+    // business name as HTML.
+    text.textContent = consentText;
+    container.appendChild(text);
+    return container;
+}
 /**
  * Create and mount payment element
  */
@@ -273,7 +305,7 @@ export function createAddressElement(elements, options, mountElement) {
 /**
  * Clean up elements and containers
  */
-export function cleanupElements(paymentElement, addressElement, paymentContainer, addressContainer, customTermsContainer) {
+export function cleanupElements(paymentElement, addressElement, paymentContainer, addressContainer, customTermsContainer, cardConsentContainer) {
     paymentElement.unmount();
     if (addressElement) {
         addressElement.unmount();
@@ -288,6 +320,9 @@ export function cleanupElements(paymentElement, addressElement, paymentContainer
     if (customTermsContainer) {
         customTermsContainer.remove();
     }
+    if (cardConsentContainer) {
+        cardConsentContainer.remove();
+    }
 }
 /**
  * Handle save card operation

package/dist/v1/stripe/terms.d.ts

@@ -29,6 +29,28 @@ export declare const ACH_TERMS_TEXT: {
     readonly EXPANDED_TERMS_PRIVACY_PREFIX: "Lightspeed may collect or access certain payment-related information as described in the platform agreement and";
     readonly PRIVACY_POLICY_LINK_TEXT: "Privacy Policy";
 };
+/**
+ * Partner card consent text — replaces Stripe's built-in card mandate (whose
+ * wording is fixed by Stripe and cannot be customized) with copy the SDK renders
+ * itself for partner card payments. `{business}` and `{reason}` are interpolated
+ * at render time (reason supplied by the caller, e.g. via
+ * `getPartnerCardConsentReason`).
+ *
+ * NOTE: The SDK does not translate these strings at runtime — they render in
+ * English regardless of the session `locale` (which only localizes Stripe's own
+ * Element UI). Like the ACH strings above, they are kept as plain constants so
+ * they *could* be extracted for Transifex later, but no runtime i18n exists
+ * today.
+ */
+export declare const PARTNER_CARD_CONSENT_TEXT: {
+    readonly MANDATORY_TEMPLATE: "By providing your card information, you authorize {business} to charge your card for {reason} in accordance with their terms.";
+    readonly CHECKBOX_TEMPLATE: "By checking the box above, you authorize {business} to charge your card for {reason} in accordance with their terms.";
+};
+/**
+ * The configured consent reason for a partner grantor, or `undefined` if the
+ * partner has none (in which case no custom card consent is rendered).
+ */
+export declare function getPartnerCardConsentReason(grantor?: string): string | undefined;
 export declare const ACH_TERMS_URL: {
     readonly STRIPE_ACH_AUTHORIZATION: "https://stripe.com/legal/ach-payments/authorization";
     readonly PRIVACY_POLICY: "https://www.lightspeedhq.com/legal/privacy-policy/";

package/dist/v1/stripe/terms.js

@@ -34,6 +34,45 @@ export var ACH_TERMS_TEXT = {
     EXPANDED_TERMS_PRIVACY_PREFIX: 'Lightspeed may collect or access certain payment-related information as described in the platform agreement and',
     PRIVACY_POLICY_LINK_TEXT: 'Privacy Policy',
 };
+/**
+ * Partner card consent text — replaces Stripe's built-in card mandate (whose
+ * wording is fixed by Stripe and cannot be customized) with copy the SDK renders
+ * itself for partner card payments. `{business}` and `{reason}` are interpolated
+ * at render time (reason supplied by the caller, e.g. via
+ * `getPartnerCardConsentReason`).
+ *
+ * NOTE: The SDK does not translate these strings at runtime — they render in
+ * English regardless of the session `locale` (which only localizes Stripe's own
+ * Element UI). Like the ACH strings above, they are kept as plain constants so
+ * they *could* be extracted for Transifex later, but no runtime i18n exists
+ * today.
+ */
+export var PARTNER_CARD_CONSENT_TEXT = {
+    // save-card flow: consent given by providing card details.
+    MANDATORY_TEMPLATE: 'By providing your card information, you authorize {business} to charge your card for {reason} in accordance with their terms.',
+    // pay-and-save flow: consent tied to the save checkbox.
+    CHECKBOX_TEMPLATE: 'By checking the box above, you authorize {business} to charge your card for {reason} in accordance with their terms.',
+};
+/**
+ * Consent reason per partner grantor — what the saved card may be charged for,
+ * keyed by the grantor segment of the product (`partner:{grantor}::...`). Add an
+ * entry to offer custom card consent to another partner. Hardcoded for now; may
+ * become a per-session input from Processing Service later.
+ */
+var PARTNER_CARD_CONSENT_REASONS = {
+    golf: 'future payments towards charges related to tee-time bookings and/or house accounts as applicable',
+};
+/**
+ * The configured consent reason for a partner grantor, or `undefined` if the
+ * partner has none (in which case no custom card consent is rendered).
+ */
+export function getPartnerCardConsentReason(grantor) {
+    if (grantor &&
+        Object.prototype.hasOwnProperty.call(PARTNER_CARD_CONSENT_REASONS, grantor)) {
+        return PARTNER_CARD_CONSENT_REASONS[grantor];
+    }
+    return undefined;
+}
 export var ACH_TERMS_URL = {
     STRIPE_ACH_AUTHORIZATION: 'https://stripe.com/legal/ach-payments/authorization',
     PRIVACY_POLICY: 'https://www.lightspeedhq.com/legal/privacy-policy/',

package/dist/v1/stripe/widgets/moto.js

@@ -34,26 +34,40 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
-import { initStripe, createPaymentElementOptions, createPaymentElement, cleanupElements, createSubmitHandler, setupChangeEventHandler, } from '../shared';
+import { initStripe, createPaymentElementOptions, createPaymentElement, buildCardConsentText, createCardConsentElement, cleanupElements, createSubmitHandler, setupChangeEventHandler, } from '../shared';
+import { getPartnerGrantor } from '../partnerProduct';
+import { getPartnerCardConsentReason } from '../terms';
 /**
  * Mount MOTO widget for moto and moto-with-save session types
  * MOTO (Mail Order/Telephone Order) forms don't require address collection
  */
 export function mountMotoWidget(mountElement, session, eventBroadcaster, defaultValues, theme) {
     return __awaiter(this, void 0, void 0, function () {
-        var _a, stripe, elements, paymentOptions, _b, paymentElement, paymentContainer, customTermsContainer;
+        var _a, stripe, elements, businessName, consentReason, renderPartnerConsent, cardMandate, paymentOptions, _b, paymentElement, paymentContainer, customTermsContainer, cardConsentContainer;
         return __generator(this, function (_c) {
             switch (_c.label) {
                 case 0: return [4 /*yield*/, initStripe(session.context, theme)];
                 case 1:
                     _a = _c.sent(), stripe = _a.stripe, elements = _a.elements;
-                    paymentOptions = createPaymentElementOptions(defaultValues, theme, false, session.context.businessName);
+                    businessName = session.context.businessName;
+                    consentReason = getPartnerCardConsentReason(getPartnerGrantor(session.metadata.product));
+                    renderPartnerConsent = session.metadata.sessionType === 'save' &&
+                        !!businessName &&
+                        !!consentReason;
+                    cardMandate = renderPartnerConsent
+                        ? 'never'
+                        : undefined;
+                    paymentOptions = createPaymentElementOptions(defaultValues, theme, false, businessName, cardMandate);
                     _b = createPaymentElement(elements, paymentOptions, mountElement, eventBroadcaster), paymentElement = _b.element, paymentContainer = _b.container, customTermsContainer = _b.customTermsContainer;
+                    if (renderPartnerConsent) {
+                        cardConsentContainer = createCardConsentElement(buildCardConsentText(businessName, consentReason, 'mandatory'));
+                        mountElement.appendChild(cardConsentContainer);
+                    }
                     // Setup change handler for payment element only (MOTO forms don't have address element)
                     setupChangeEventHandler(paymentElement, eventBroadcaster);
                     return [2 /*return*/, {
                             unmount: function () {
-                                cleanupElements(paymentElement, null, paymentContainer, null, customTermsContainer);
+                                cleanupElements(paymentElement, null, paymentContainer, null, customTermsContainer, cardConsentContainer);
                             },
                             submit: createSubmitHandler(stripe, elements, session, eventBroadcaster, null),
                         }];

package/dist/v1/stripe/widgets/payment.js

@@ -34,18 +34,22 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
-import { initStripe, createPaymentElementOptions, createAddressElementOptions, createPaymentElement, createAddressElement, cleanupElements, createSubmitHandler, setupChangeEventHandler, } from '../shared';
+import { initStripe, createPaymentElementOptions, createAddressElementOptions, createPaymentElement, createAddressElement, buildCardConsentText, createCardConsentElement, cleanupElements, createSubmitHandler, setupChangeEventHandler, } from '../shared';
+import { getPartnerGrantor } from '../partnerProduct';
+import { getPartnerCardConsentReason } from '../terms';
 /**
  * Mount payment widget for payment and payment-with-save session types
  */
 export function mountPaymentWidget(mountElement, session, eventBroadcaster, defaultValues, theme) {
     return __awaiter(this, void 0, void 0, function () {
-        var _a, stripe, elements, productMetadata, isPartnerProduct, addressElement, addressContainer, addressOptions, created, showCardMandate, paymentOptions, _b, paymentElement, paymentContainer, customTermsContainer;
+        var _a, stripe, elements, businessName, isPayWithSave, productMetadata, isPartnerProduct, addressElement, addressContainer, addressOptions, created, consentReason, renderPartnerConsent, cardMandate, paymentOptions, _b, paymentElement, paymentContainer, customTermsContainer, cardConsentContainer;
         return __generator(this, function (_c) {
             switch (_c.label) {
                 case 0: return [4 /*yield*/, initStripe(session.context, theme)];
                 case 1:
                     _a = _c.sent(), stripe = _a.stripe, elements = _a.elements;
+                    businessName = session.context.businessName;
+                    isPayWithSave = session.metadata.sessionType === 'payment-with-save';
                     productMetadata = session.metadata.product;
                     isPartnerProduct = typeof productMetadata === 'string' &&
                         productMetadata.startsWith('partner:');
@@ -57,16 +61,24 @@ export function mountPaymentWidget(mountElement, session, eventBroadcaster, defa
                         addressElement = created.element;
                         addressContainer = created.container;
                     }
-                    showCardMandate = session.metadata.sessionType === 'payment-with-save' &&
-                        !!session.context.businessName &&
-                        isPartnerProduct;
-                    paymentOptions = createPaymentElementOptions(defaultValues, theme, !!addressElement, session.context.businessName, showCardMandate);
+                    consentReason = getPartnerCardConsentReason(getPartnerGrantor(productMetadata));
+                    renderPartnerConsent = isPayWithSave && !!businessName && !!consentReason;
+                    cardMandate = renderPartnerConsent
+                        ? 'never'
+                        : isPayWithSave && !!businessName && isPartnerProduct
+                            ? 'always'
+                            : undefined;
+                    paymentOptions = createPaymentElementOptions(defaultValues, theme, !!addressElement, businessName, cardMandate);
                     _b = createPaymentElement(elements, paymentOptions, mountElement, eventBroadcaster), paymentElement = _b.element, paymentContainer = _b.container, customTermsContainer = _b.customTermsContainer;
+                    if (renderPartnerConsent) {
+                        cardConsentContainer = createCardConsentElement(buildCardConsentText(businessName, consentReason, 'checkbox'));
+                        mountElement.appendChild(cardConsentContainer);
+                    }
                     // Setup change handler that emits Complete only when both elements are complete
                     setupChangeEventHandler(paymentElement, eventBroadcaster, addressElement);
                     return [2 /*return*/, {
                             unmount: function () {
-                                cleanupElements(paymentElement, addressElement, paymentContainer, addressContainer, customTermsContainer);
+                                cleanupElements(paymentElement, addressElement, paymentContainer, addressContainer, customTermsContainer, cardConsentContainer);
                             },
                             submit: createSubmitHandler(stripe, elements, session, eventBroadcaster, addressElement),
                         }];

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.7.1";
+export declare const SDK_VERSION = "1.7.3";

package/dist/version.js

@@ -1,3 +1,3 @@
 // This file is auto-generated during the build process
 // DO NOT EDIT MANUALLY - Version is extracted from package.json
-export var SDK_VERSION = '1.7.1';
+export var SDK_VERSION = '1.7.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightspeed/online-payments-sdk",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Process online-payments with Lightspeed Payments",
   "author": "Lightspeed Commerce Inc.",
   "license": "SEE LICENSE IN LICENSE.md",

package/styles/lightspeed-global-styles.css

@@ -66,6 +66,24 @@
   margin-bottom: 0;
 }
 
+/* Custom card consent text for partner card payments. Replaces Stripe's
+   built-in card mandate (suppressed via terms.card: 'never'). Typography matches
+   the ACH custom terms text above. */
+
+.stripe-card-consent-container {
+  padding: 0;
+}
+
+.stripe-card-consent-text {
+  margin: 16px 0 0 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
+    Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+  font-size: 0.93rem;
+  font-weight: 400;
+  line-height: 1.5;
+  color: #30313d;
+}
+
 /* Invoicing theme: only override font-family to match the Inter font
    passed to Stripe Elements via the invoicing theme config. */
 
@@ -74,7 +92,8 @@
 }
 
 .lsp-theme-invoicing .stripe-custom-terms-text,
-.lsp-theme-invoicing .stripe-expandable-terms-content p {
+.lsp-theme-invoicing .stripe-expandable-terms-content p,
+.lsp-theme-invoicing .stripe-card-consent-text {
   font-family: 'Inter', system-ui, sans-serif;
 }