Credential-less discovery

What it is & when to use it

The default Connect flow asks the user for the credentials of each biller they want to link. Credential-less discovery is a different entry point: the user supplies their identity instead, an aggregator returns the accounts it can attribute to that identity, and the user picks which ones to link. "Credential-less" means no per-biller username/password — it does not mean no link token.

The link token still rides over the SDK INIT message exactly like the embedded Connect flow. Once the user selects accounts, the existing account-selection → link pipeline completes and fires the link.completed webhook — identical to a credentialed link. Nothing downstream changes.

Quick start

Construct a BillerApiElements client, then call discover() with a sandbox link token and a host element. Discovery renders inline into the element you provide — there is no modal overlay.

import { BillerApiElements } from 'billerapi-js';

// 1. One client for every flow
const elements = new BillerApiElements({
  clientId: 'your_client_id',
  environment: 'sandbox', // credential-less discovery is sandbox-only
});

// 2. Launch inline discovery with a sandbox link_token from your server
const handler = elements.discover({
  linkToken: 'lt_xxx',                                  // from your server
  hostElement: document.getElementById('billerapi-discover'), // inline mount target
  theme: 'light',                                       // 'light' | 'dark' | ElementsTheme
  onSuccess: (publicToken, metadata) => {
    // Send publicToken to your server to exchange for an access token.
    // The link.completed webhook is the source of truth.
    console.log('Linked!', metadata);
  },
  onExit: (error) => {
    if (error) console.error('Discovery error:', error.code, error.message);
  },
  onEvent: (eventName, metadata) => {
    // Optional lifecycle telemetry
  },
});

// 3. Render the secure iframe inline (no modal). Returns a Promise.
await handler.mount();

// handler.isMounted() -> boolean;  handler.unmount() tears it down.

discover() & useDiscover()

Both take the same options object. The vanilla factory returns a handler; the hook returns the same handler methods plus reactive ready / error state.

Handler (returned by discover(), and surfaced by useDiscover()):

• mount(): Promise<void> — render the inline iframe into hostElement.
• unmount(): void — tear it down (idempotent).
• isMounted(): boolean — current mount state.

The hook additionally returns ready (SDK loaded & safe to mount()) and error.

The identity model

The user submits four identity fields — all required, all snake_case on the wire. This mock deliberately collects no SSN and no date of birth: it is a PII-light surface by design.

The sandbox endpoint

The SDK drives this for you, but it maps to a single sandbox endpoint. The link token in the path is the credential — there is no API key header on this call, mirroring the other link-token routes on the sandbox host.

# Sandbox host serves sb_ / bak_test_ tokens.
# The {link_token} in the path is the credential (no secret header).
curl -X POST https://sandbox.api.billerapi.com/link/token/lt_xxx/discover-by-identity \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Ada Lovelace",
    "phone": "5551234242",
    "email": "ada@example.com",
    "postal_code": "94105"
  }'

# => 202 Accepted
# { "success": true, "discovered_count": 2 }
#
# When the CREDENTIALLESS_DISCOVERY_ENABLED flag is OFF (the default):
# => 404 Not Found

On success the sandbox pre-loads the link session with the discovered accounts and emits the standard account-selection step. The user selects accounts, the existing exchange completes, and the link.completed webhook fires — the same terminal signal as any credentialed link.

The vendor-swappable provider seam

Discovery is implemented behind a provider interface so the aggregator is a swappable dependency. Today the only binding is a deterministic mock aggregator that returns synthetic liabilities. A real Method / Spinwheel / bureau adapter can be dropped in later by implementing the same interface — no change to the SDK, the endpoint contract, or the downstream link pipeline.

// The identity the caller submits (PII-light: no SSN / no DOB).
interface DiscoveryIdentity {
  full_name: string;
  phone: string;
  email: string;
  postal_code: string;
}

// A single discovered account/liability the user can one-tap to link.
interface DiscoveredLiability {
  id: string;          // 'sb_disc_acct_<hex>'
  biller_id: string;   // synthetic in the mock, e.g. 'sb_utility'
  biller_name: string; // 'Sandbox Utility'
  account_name: string;
  mask: string;        // '****4242'
  type: string;        // 'utility' | 'telecom' | 'insurance' | ...
}

// The swap point. The mock implements this today; a real vendor adapter
// (Method / Spinwheel / a bureau) implements the same method later.
interface CredentiallessDiscoveryProvider {
  discover(identity: DiscoveryIdentity): Promise<DiscoveredLiability[]>;
}

Related