Designing APIs for Alternative Credit Scoring

// extract.mjs: Queries API, transforms metrics to canonical fields
const API_URL = process.env.FAKE_PAYMENTS_API_URL ?? "http://fake-payments-api:4200";
const API_KEY = process.env.FAKE_PAYMENTS_API_KEY ?? "demo-key";

const adapter = {
  id: "payments-network-adapter-v1",
  category: "payment-network",
  version: 1,
  produces: [
    "monthlyVolume3m",
    "monthlyVolume12m",
    "arpuStability12m",
    "disputeRate12m",
    "customerConcentrationTop5Pct",
    "activeTenureMonths"
  ],

  async fetch(identity) {
    if (!identity?.ic || !identity?.fullName) {
      throw new Error("fake-payments-v1: identity.ic and identity.fullName are required");
    }
    const res = await fetch(`${API_URL}/v1/merchants/lookup`, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-api-key": API_KEY
      },
      body: JSON.stringify({ ic: identity.ic, fullName: identity.fullName })
    });
    
    if (!res.ok) {
      throw new Error(`fake-payments-v1 fetch failed: HTTP ${res.status}`);
    }
    return res.json();
  },

  async extract(raw) {
    const metrics = raw.paymentsMetrics ?? {};
    return [{
      instanceKey: "default",
      observedAt: new Date().toISOString(),
      values: {
        monthlyVolume3m: Number(metrics.monthlyVolumeMyrT3 ?? 0),
        monthlyVolume12m: Number(metrics.monthlyVolumeMyrT12 ?? 0),
        arpuStability12m: Number(metrics.arpuStability12m ?? 0),
        disputeRate12m: Number(metrics.disputeRate12m ?? 0),
        customerConcentrationTop5Pct: Number(metrics.customerConcentrationTop5Pct ?? 0),
        activeTenureMonths: Number(metrics.activeTenureMonths ?? 0)
      }
    }];
  }
};

export default adapter;

// test.mjs: Offline verification tests
import { runFixtures } from "@finsys/adapter-toolkit";
import adapter from "./extract.mjs";

const fixtures = [
  {
    name: "hassan-trading",
    identity: { ihsId: 1, ic: "850101015432", fullName: "Aiman bin Hassan" },
    expected: [
      {
        instanceKey: "default",
        values: {
          activeTenureMonths: 38,
          monthlyVolume3m: 285000
        }
      }
    ]
  }
];

const results = await runFixtures(adapter, fixtures);
console.log(results);
if (results.some(r => !r.ok)) {
  console.error("❌ Payments test suite failed");
  process.exit(1);
} else {
  console.log("✅ Payments metrics verification passed!");
}