How to Build a transaction monitoring Agent Using LangChain in Python for payments

A transaction monitoring agent watches payment events, scores them against risk rules, and explains why a transaction looks normal or suspicious. For payments teams, this matters because you need fast triage, consistent decisions, and an audit trail that satisfies compliance without pushing every case to a human.

Architecture

A production transaction monitoring agent for payments needs these pieces:

• •

  Transaction ingestion layer

  • •Pulls payment events from Kafka, SQS, a webhook, or a database stream.
  • •Normalizes fields like amount, currency, merchant_id, country, customer_id, and timestamp.
• •

  Risk feature builder

  • •Computes payment-specific signals:
    • •velocity checks
    • •amount deviation from customer baseline
    • •country mismatch
    • •merchant category risk
    • •chargeback history
  • •Keeps deterministic logic outside the LLM.
• •

  LangChain reasoning layer

  • •Uses ChatOpenAI plus a prompt template to explain the alert and recommend next actions.
  • •Produces structured output so downstream systems can route cases reliably.
• •

  Policy and compliance guardrails

  • •Enforces PCI, AML/KYC, sanctions screening, and data minimization.
  • •Prevents raw PANs, CVVs, and unnecessary PII from reaching the model.
• •

  Case management output

  • •Writes decisions to an internal queue, SIEM, or case management tool.
  • •Stores full audit metadata: inputs, rules triggered, model version, timestamp, and reviewer action.

Implementation

1) Install dependencies and define the event schema

Use LangChain with Pydantic models so your agent returns structured results instead of free-form text. For payments work, that structure is what makes audit and automation possible.

pip install langchain langchain-openai pydantic

from typing import List, Literal
from pydantic import BaseModel, Field

class TransactionEvent(BaseModel):
    transaction_id: str
    customer_id: str
    merchant_id: str
    amount: float
    currency: str
    country: str
    card_present: bool
    timestamp: str
    historical_avg_amount: float = Field(..., description="Customer baseline spend")
    recent_txn_count_1h: int = Field(..., description="Velocity signal")
    sanctions_hit: bool = False

class RiskAssessment(BaseModel):
    risk_level: Literal["low", "medium", "high"]
    reasons: List[str]
    recommended_action: Literal["approve", "review", "block"]

2) Build deterministic payment signals first

Do not ask the model to calculate basic risk features from scratch. Compute them in Python so the agent stays stable and explainable.

def build_signals(txn: TransactionEvent) -> dict:
    amount_ratio = txn.amount / max(txn.historical_avg_amount, 1.0)
    high_velocity = txn.recent_txn_count_1h >= 5
    unusual_amount = amount_ratio >= 3.0
    cross_border = txn.country not in {"US", "CA", "GB"}
    
    return {
        "amount_ratio": round(amount_ratio, 2),
        "high_velocity": high_velocity,
        "unusual_amount": unusual_amount,
        "cross_border": cross_border,
        "sanctions_hit": txn.sanctions_hit,
        "raw_event": txn.model_dump(),
    }

3) Create the LangChain agent prompt and structured output chain

This pattern uses ChatOpenAI, ChatPromptTemplate, and .with_structured_output() to force a valid response shape. That is the right default for transaction monitoring.

import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system",
     """You are a payment transaction monitoring analyst.
Return only a structured assessment.
Use these rules:
- If sanctions_hit is true or there are multiple strong fraud indicators, recommend block.
- If there is one major anomaly or moderate velocity risk, recommend review.
- Otherwise approve.
Do not mention raw PANs or sensitive personal data."""),
    ("human",
     """Assess this payment transaction:
{signals}

Output must match the schema exactly.""")
])

llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
    api_key=os.environ["OPENAI_API_KEY"],
)

chain = prompt | llm.with_structured_output(RiskAssessment)

4) Run the agent on a real transaction event

This is where you combine deterministic signals with LLM reasoning. The model explains the decision; your code owns the final policy.

txn = TransactionEvent(
    transaction_id="txn_10001",
    customer_id="cus_7788",
    merchant_id="mrc_4421",
    amount=1250.00,
    currency="USD",
    country="NG",
    card_present=False,
    timestamp="2026-04-21T10:15:00Z",
    historical_avg_amount=120.00,
    recent_txn_count_1h=7,
    sanctions_hit=False,
)

signals = build_signals(txn)
result = chain.invoke({"signals": signals})

print(result.risk_level)
print(result.reasons)
print(result.recommended_action)

If you want full traceability in production, wrap this with LangChain callbacks or LangSmith tracing so every decision is replayable during audit review.

Production Considerations

• •

  Keep sensitive data out of prompts

  • •Never send PANs, CVVs, bank account numbers, or full addresses to the model.
  • •Tokenize identifiers before they enter LangChain.
• •

  Enforce data residency

  • •Payments data often cannot leave a specific region.
  • •Host your model endpoint in-region or use an approved private deployment path.
• •

  Log decisions for audit

  • •Store input features, triggered rules, model output, human override status, and policy version.
  • •Regulators will care more about reproducibility than clever prompting.
• •

  Put hard limits around automation

  • •Auto-block only when deterministic policy plus model output crosses a strict threshold.
  • •Send borderline cases to human review.

Common Pitfalls

1. •

   Letting the LLM do all risk scoring

   • •Bad pattern: asking the model to infer everything from raw JSON.
   • •Fix: compute velocity, deviation, sanctions flags, and geography rules in Python first.
2. •

   Returning free-form text instead of structured output

   • •Bad pattern: parsing paragraphs into downstream systems.
   • •Fix: use Pydantic models with .with_structured_output() so outputs are machine-safe.
3. •

   Ignoring compliance constraints

   • •Bad pattern: sending full customer profiles to a hosted model without controls.
   • •Fix: minimize fields, redact sensitive data, pin regions for residency requirements, and keep an immutable audit log.

A good payments monitoring agent does not replace your fraud engine. It sits on top of deterministic controls and gives analysts faster explanations, cleaner triage queues, and better evidence when compliance asks why a transfer was approved or blocked.

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.