Borrower SDK

Embed a widget from borrower app in your site or app. You open the modal, the borrower completes the payment flow inside a secure iframe, and you get a confirmation object back — your code never touches payment data or PII.

• Framework-agnostic core (create()), plus a React hook (useBorrowerPayment).
• No dependencies. React is an optional peer dependency, only needed for the /react entry.
• Isolated by design. The whole flow (identity verification, loan review, ACH payment) runs inside an iframe served by the lender's deployment, with the lender's approved branding (or the default FCI branding if the lender hasn't configured one). No CSS or payment logic leaks into your page.

Installation

npm install @myfci/borrower-sdk
# or: pnpm add @myfci/borrower-sdk
# or: yarn add @myfci/borrower-sdk

Or load it from the lender's CDN with no build step — this exposes a global UnifiedBorrower:

<script src="https://YOUR-LENDER-HOST/sdk/v1/borrower-sdk.js"></script>

Prerequisites

You need a JWT issued for a specific borrower + loan. Your backend obtains it through a token exchange with the identity service and hands it to your frontend — you never mint it yourself. The token carries the loan and the target environment, so there is nothing else to configure: no host URLs, no API keys.

Quick start (vanilla / any framework)

import { create } from '@myfci/borrower-sdk';

const handler = create({
  widget: 'payment',
  jwt: 'YOUR_JWT', // issued by the identity service for the borrower + loan
  onSuccess(result) {
    console.log('Payment confirmed', result.confirmationNumber, result.amount);
  },
  onExit(error) {
    if (error) console.warn('Closed with error', error.code);
  },
});

document.getElementById('pay').addEventListener('click', () => handler.open());

create() mounts a hidden iframe immediately, so open() shows the modal instantly. Call handler.destroy() when you no longer need it.

With the CDN build, replace the import with the global: UnifiedBorrower.create({ ... }).

React

import { useBorrowerPayment } from '@myfci/borrower-sdk/react';
import type { BorrowerPaymentResult } from '@myfci/borrower-sdk/react';

function PayButton({ jwt }: { jwt: string }) {
  const { open, ready, error, exit } = useBorrowerPayment({
    jwt,
    onSuccess: (result: BorrowerPaymentResult) => saveConfirmation(result),
    onExit: (err) => {
      if (err) console.warn(err.code);
    },
  });

  if (error) return <p role="alert">{error.message}</p>;

  return (
    <button onClick={() => open()} disabled={!ready}>
      Pay now
    </button>
  );
}

The hook recreates its handler when jwt or widget change; changing the callbacks alone does not tear down the iframe. Works with React 17, 18, and 19 — the modal runs isolated inside the iframe, so there is no version conflict with your app.

Options

| Option | Required | Description | | --- | --- | --- | | widget | — | Widget to open. Currently 'payment' (default). | | jwt | ✅ | Signed JWT that authorizes the session and identifies the borrower + loan. | | onSuccess(result) | — | Called with a BorrowerPaymentResult when a payment completes. | | onExit(error?) | — | Called when the borrower closes without completing, or on a terminal error (error.code set). | | onEvent(name, meta) | — | Optional analytics hook. |

A missing or malformed jwt fails loud: create() throws UnifiedBorrowerError, and the React hook sets error and logs to the console (prefixed [UnifiedBorrower]) — a misconfiguration is never silent.

Handler / hook return

| Member | Type | Description | | --- | --- | --- | | open | () => void | Shows the modal. | | exit | () => void | Closes the modal programmatically. | | destroy | () => void | Removes the iframe and listeners (vanilla only — the hook cleans up on unmount). | | ready | boolean | React only — true once the widget is initialized and can be opened. | | error | UnifiedBorrowerError \| null | React only — set when the input was rejected. |

Result object

interface BorrowerPaymentResult {
  confirmationNumber: string;
  amount: number;
  paymentDate: string; // as shown on the ACH confirmation
  paymentMethod: 'ach';
  loanNumberMasked: string; // e.g. "••••3456"
}

No raw PII is returned — just confirmation data you can store or display.

Environments

The JWT's env claim selects the environment (sandbox or prod) and the SDK resolves the right host automatically. Switching from sandbox to production means changing the JWT you pass in — nothing else. With the CDN build, the host is inferred from the <script> origin instead.

Versioning

The npm package follows semver. The CDN path (/sdk/v1) pins the major version of the message protocol — a breaking protocol change ships under /sdk/v2, and your integration keeps working on v1 until you migrate.

Browser support

Modern evergreen browsers (ES2019). The package ships as ESM.