How to Build a fraud detection Agent Using LlamaIndex in TypeScript for payments

A fraud detection agent for payments watches transaction context, compares it against policy and historical patterns, and returns a risk decision with evidence. It matters because card-not-present fraud, account takeover, and mule activity are expensive, noisy, and time-sensitive; you need a system that can explain why a payment was flagged, not just say “high risk.”

Architecture

Build this agent as a small set of explicit components:

• •

  Transaction intake layer

  • •Normalizes payment events from your processor, gateway, or ledger.
  • •Fields should include amount, currency, merchant, customer ID, device fingerprint, IP geo, BIN country, velocity counters, and auth outcome.
• •

  Policy retrieval layer

  • •Stores fraud rules, chargeback playbooks, and compliance notes.
  • •Use LlamaIndex retrieval so the agent can pull relevant policy text before making a decision.
• •

  Risk reasoning agent

  • •Uses an LLM through LlamaIndex to classify the transaction as approve, review, or block.
  • •Must return structured output with rationale and evidence.
• •

  Audit trail store

  • •Persists the input features, retrieved policy snippets, model output, and final decision.
  • •This is non-negotiable in payments because disputes and regulator reviews require traceability.
• •

  Human review handoff

  • •Routes borderline cases to an analyst queue.
  • •The agent should never auto-decline high-value transactions without a confidence threshold and policy backing.

Implementation

1) Install the packages and wire up the LLM

Use the TypeScript LlamaIndex SDK with an OpenAI-compatible model. For production payments systems, keep the model behind environment-based config so you can swap providers without changing business logic.

npm install llamaindex zod

import {
  Settings,
  Document,
  VectorStoreIndex,
  QueryEngineTool,
  ToolMetadata,
  FunctionAgent,
} from "llamaindex";

Settings.llm = {
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY!,
};

2) Load fraud policy documents into an index

Put your internal fraud rules into documents. In practice these come from runbooks, chargeback SOPs, KYC policy docs, and merchant-specific controls.

const docs = [
  new Document({
    text: `
Fraud policy:
- Block transactions over $5,000 when device is new AND IP country differs from BIN country.
- Review any payment with velocity > 5 attempts in 10 minutes.
- Block if chargeback history exceeds 3% for this customer segment.
- Always preserve audit logs for at least 7 years.
`,
    metadata: { source: "fraud-policy-v1", region: "us-east-1" },
  }),
];

const index = await VectorStoreIndex.fromDocuments(docs);
const retriever = index.asRetriever();

3) Expose policy lookup as a tool and build the agent

This pattern lets the agent retrieve only relevant rules before deciding. That reduces prompt size and makes decisions easier to audit.

const policyTool = new QueryEngineTool({
  queryEngine: index.asQueryEngine(),
  metadata: new ToolMetadata({
    name: "fraud_policy_lookup",
    description:
      "Retrieve fraud rules, thresholds, and review criteria for payment decisions.",
  }),
});

const agent = new FunctionAgent({
  tools: [policyTool],
});

4) Classify a transaction with structured output

Ask for a strict JSON response. In payments you want deterministic downstream handling: no free-form prose driving automated declines.

type FraudDecision = {
  decision: "approve" | "review" | "block";
  confidence: number;
  reasons: string[];
};

const transaction = {
  transactionId: "txn_98321",
  amount: 7200,
  currency: "USD",
  customerId: "cus_4421",
  deviceNew: true,
  ipCountry: "NG",
  binCountry: "US",
  attemptsLast10Min: 2,
};

const response = await agent.chat({
  message: `
You are a payment fraud analyst.
Use the policy lookup tool before deciding.

Transaction:
${JSON.stringify(transaction)}

Return JSON only with:
decision (approve|review|block),
confidence (0-1),
reasons (array of strings).
`,
});

console.log(response.message);

If you want stronger control over output shape, validate it before sending anything to downstream systems:

import { z } from "zod";

const FraudDecisionSchema = z.object({
  decision: z.enum(["approve", "review", "block"]),
  confidence: z.number().min(0).max(1),
  reasons: z.array(z.string()),
});

const parsed = FraudDecisionSchema.parse(JSON.parse(response.message));

Production Considerations

• •

  Keep sensitive payment data out of prompts

  Do not send PANs, CVVs, or full bank details into the model. Tokenize identifiers and pass only the minimum feature set needed for risk reasoning.

• •

  Persist every decision for audit

  Store input features, retrieved policies, model version, prompt hash, output JSON, and final action. This is required for dispute handling and internal controls.

• •

  Respect data residency

  If you operate across regions like EU/UK/US, pin vector stores and inference endpoints to approved regions. Fraud data often contains personal data that cannot cross borders casually.

• •

  Add hard guardrails outside the model

  Enforce deterministic rules in code for sanctions hits, blacklisted merchants, or impossible geographies. The agent should assist decisions; it should not be your only control.

Common Pitfalls

1. •

   Using free-form LLM output in production decisions

   If your downstream service parses prose like “this looks suspicious,” you will eventually ship bad declines. Force JSON output and validate it with Zod before acting on it.

2. •

   Letting the model see raw cardholder data

   That creates unnecessary PCI exposure. Replace PANs with tokens or hashes and pass derived features like country mismatch or velocity counts instead.

3. •

   Treating retrieval as optional

   A fraud agent without current policy context will drift from your actual controls. Put thresholds and escalation rules in indexed documents so analysts can update behavior without redeploying code.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.