AltFiScore Node.js SDK

Official Node.js / TypeScript client for the AltFiScore alternative credit scoring and loan decisioning API.

Alternative credit scoring and decisioning infrastructure for banks, credit unions, fintechs, BNPL providers, and embedded lenders.

Installation

npm install altfiscore

Requires Node.js 18+ (uses the built-in fetch). Ships with TypeScript types.

Quickstart

import { AltFiScore } from "altfiscore";

const client = new AltFiScore("altfi_test_...");

const decision = await client.decisions.bnpl({
  consumer: {
    first_name: "Ada",
    last_name: "Okoro",
    email: "[email protected]",
    dob: "1990-01-15",
    ssn_last4: "1234",
  },
  order: {
    amount: "450.00",
    currency: "USD",
    installment_count: 4,
  },
});

if (decision.isApproved) {
  console.log(`Approved ${decision.approvedAmount} at ${decision.apr}% APR`);
  for (const installment of decision.paymentSchedule) {
    console.log(installment.due_date, installment.amount);
  }
} else if (decision.isReferred) {
  console.log("Counter-offer:", decision.counterOffer);
} else if (decision.isDeclined) {
  for (const reason of decision.declineReasons) {
    console.log(reason.code, reason.reason);
  }
}

Products

Every product is a method on client.decisions:

await client.decisions.bnpl({ consumer, order });
await client.decisions.autoLoan({ consumer, loan, vehicle, dealer });
await client.decisions.mortgage({ consumer, loan, property });
await client.decisions.personalLoan({ consumer, loan });
await client.decisions.creditCard({ consumer, product });

Returning consumers

Pass a consumer_id instead of full PII to score a consumer you have already onboarded:

const decision = await client.decisions.personalLoan({
  consumer: { consumer_id: "b0c9ed84-f66c-4598-b50a-a0d8b2ddcd04" },
  loan: { amount: "12000.00", currency: "USD", term_months: 36 },
});

Pending decisions (consumer verification)

Larger amounts trigger enhanced or hard KYC. When that happens the decision is returned in a pending state:

const decision = await client.decisions.mortgage({ consumer, loan, property });

if (decision.isPending) {
  // Redirect the consumer to complete verification
  console.log(decision.consumerCompleteUrl);

  // Then poll until the decision is final
  const final = await client.decisions.poll("mortgage", decision.decisionId!, {
    timeoutMs: 180000,
  });
  console.log(final.outcome);
}

Idempotency

Pass an idempotencyKey to make create calls safe to retry. Reusing a key returns the original decision instead of creating a new one:

const decision = await client.decisions.bnpl({
  consumer,
  order,
  idempotencyKey: "order-98a7f3",
});

Error handling

import {
  AuthenticationError,
  InvalidRequestError,
  RateLimitError,
  APIError,
} from "altfiscore";

try {
  const decision = await client.decisions.bnpl({ consumer, order });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // bad or revoked API key
  } else if (err instanceof InvalidRequestError) {
    // 400/422 - inspect err.body for details
  } else if (err instanceof RateLimitError) {
    // 429 - back off and retry
  } else if (err instanceof APIError) {
    // 5xx or unexpected - err.statusCode available
  }
}

A declined applicant is not an error - it is a successful decision with decision.isDeclined === true. Exceptions are only thrown for transport and API-level failures.

Configuration

const client = new AltFiScore("altfi_live_...", {
  baseUrl: "https://api.altfiscore.com", // override for sandbox/self-host
  timeout: 30000,                         // per-request milliseconds
  maxRetries: 2,                          // idempotent requests only
});

Documentation

Full API reference: https://altfiscore.com/developers

License

MIT