Embedded Payments SDK

Accept card and ACH payments in an embedded payment modal. Sessions authenticate by publishable keys with allowed origins.

Installation

CDN

The CDN build sets window.FindustryAI.

<!-- Production -->
<script src="https://js.findustryai.com/v1/sdk.js"></script>

npm

Install the package, then import FindustryAI.

npm install @findustryai/js

import { FindustryAI } from "@findustryai/js";

Configuration

Initialize the SDK on page load.

const findustryAI = new FindustryAI({
  publishableKey: "pk_findustryai_live_…"
});

Payment Lightbox

Launch the payment lightbox. Pass an amount or pre-register a session and pass the sessionId.

try {
  const response = await findustryAI.lightbox.open({
    sessionId: id,
  });

  switch (response.status) {
    case "success":
      // response = { amount, fee, id, method, pricing, rate, tax, token, total }
      break;
    case "canceled":
    case "declined":
    case "expired":
      // No payment made.
      break;
    case "error":
      // No payment confirmed. See errors
      break;
  }
} catch (error) {
  // The payment modal did not open. See error.code.
}

Options

Prefill the payer:

const response = await findustryAI.lightbox.open({
  amount: 800,
  firstName: "Lorraine",
  lastName: "Morton",
  email: "example@findustryai.com",
  address: "909 Davis Street",
  city: "Evanston",
  state: "IL",
  postalCode: "60201",
  country: "US",
});

Saved Payment Methods

A successful payment's token represents the card or bank account the payer used. Pass it to lightbox.open or appraisalPayOS.open to offer that method again. The payer sees its brand or account type and last four digits, and may enter a different one. AppraisalPay OS charges a saved card the card price and a saved bank account the cash price.

const first = await findustryAI.lightbox.open({ amount: 800 });

// Later, for the same payer:
const next = await findustryAI.lightbox.open({
  amount: 40,
  token: first.token,
});

• A token from another account, or one that was deleted, is refused with 400.
• A token that cannot be charged now, such as an expired or disabled card, or a method turned off in Advanced Settings, opens the modal with an empty form and writes the reason to the console.
• With a sessionId, the session's customer must be the token's.
• token cannot be used with mode: "register".

Advanced Settings

An optional second object manages features for individual modals. Organizations may disable features they have access to but cannot enable features that are not included in their account. Invalid configurations, such as disabling all payment methods, return an error.

const response = await findustryAI.lightbox.open(
  { amount: 800 },
  { achEnabled: false },
);

Pricing Models

The pricing model is set when a merchant account is established.

Merchant-Absorbed Pricing

amount is the total paid. Standard processing rates apply.

Dual Pricing

amount is the cash price. The payer chooses between an ACH payment at the cash price and a credit or debit card payment at the card price.

Surcharge Pricing

amount is the amount without surcharge. The modal determines surcharge eligibility based on card type and presents required disclosures based on payer address.

Payment Sessions

Payment sessions require a backend authorization with your secret key prior to launching the frontend modal. The amount and other payment attributes configured on the backend. The frontend only provides a sessionId to open the modal.

POST /payment/session
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

{
  "data": {
    "amount": 800,
    "sdkProduct": "lightbox"
  }
}

// Response
const session = {
    "data": {
        "id": "abcdefab-0123-4567-8901-23456789abcd",
        "expiresAt": "2027-01-01T00:00:00.000Z"
    }
};

// Open with that id:
const response = await findustryAI.lightbox.open({
  sessionId: session.data.id
});

Publishable keys may be set to "Require a session for every payment" in the Findustry AI Portal, under the user menu › Settings › Developers.

Merchants with a custom lightbox may pass an alternative sdkProduct.

Response

lightbox.open resolves when the payment succeeds or the modal is closed. Payer may retry a declined payment before closing the modal.

Success

{
  address: string,
  amount: number,
  city: string,
  country: string,
  email: string,
  fee: number,
  firstName: string,
  id: string,
  lastName: string,
  method: "card" | "ach",
  paymentTime: string,
  phone: string,
  postalCode: string,
  pricing: "absorbed" | "dual" | "surcharge",
  rate: number,
  state: string,
  status: "success",
  tax: number,
  token: string,
  total: number
}

No Payment

{
  detail: string,
  status: "canceled" | "declined" | "expired"
}

{
  code: number,
  detail: string,
  status: "error",
  title: string
}

Fields

Security

Merchants are responsible for securing their site from attacks and protecting their checkout pages from unauthorized scripts. Findustry AI does not monitor, inventory, or control scripts on pages the merchant operates.

Frontend SDKs provide informational messages but are not proof of payment. Verify payment details by calling GET /payment/:id with a secret key or by receiving a signed web hook.

Testing

Findustry AI provides a dedicated test environment.

CDN

<!-- Test -->
<script src="https://js.test.findustryai.com/v1/sdk.js"></script>

npm

import { FindustryAI } from "@findustryai/js";

const findustryAI = new FindustryAI({
  publishableKey: "pk_findustryai_test_…",
  environment: "test"
});

Cards

Test cards use any future expiration date, for example 12/34, and the CVV 999.

Amounts under $1.00 are declined.

Bank Account

Errors

Content Security Policy

Add the SDK hosts to the page's Content-Security-Policy.

connect-src … https://js.findustryai.com https://js.test.findustryai.com;
frame-src   … https://js.findustryai.com https://js.test.findustryai.com;
script-src  … https://js.findustryai.com https://js.test.findustryai.com;

With 'strict-dynamic', add the page's nonce to the CDN <script> tag.