Noctua API — Transaction Risk Layer for Structured Payments

The Noctua API is a practical application of the conceptual framework developed in the Minerva project — Minimal Context for Transactional Fraud Assessment. Instead of following the traditional logic of accumulating more and more data to "reduce" uncertainty, Noctua takes a different approach: working with small data, that is, only with the structured information immediately available in the pacs.008 message of the ISO 20022 standard.

The innovative aspect lies precisely in this epistemological inversion. The API does not attempt to definitively classify fraud or replace robust anti-fraud systems. It operates within the limits of what can be legitimately known at the time of the transaction. From a few fields — such as value, currency, country, channel, transaction type, and identity of the parties — Noctua produces an interpretable risk score and, most importantly, makes explicit the factors that support suspicion. The focus is not on predicting intent, but on making visible what can be considered a signal under restriction.

In the financial and banking market, Noctua can be used as an initial screening layer in instant payments, as a mechanism to support low-latency decision-making, as a complementary tool for risk analysis in data-constrained environments, or even as an explainability layer for more complex models. Its design promotes transparency, traceability, and institutional accountability. This API is a public utility. It may change or be discontinued without notice.

Version

Current stable: v1.0.0

---

1. Authentication

All protected endpoints require the header:

	x-api-key: <your-base64-key>

Endpoints

API Status

• GET /status: Returns the API status.

Response:

{
	"msg": "API status 🚀",
	"name": "noctua-api",
	"version": "4.0.0",
	"uptime": 37
}

Evaluates risk

• POST /risk/evaluate: Returns the risk evaluated to transaction based in information passed

Payload:

{
	"datetime": "2026-02-18T10:59:59.999",
	"sender_name": "John DOE",
	"sender_account_type": "SVGS",
	"receiver_name": "JOAna Doe",
	"receiver_account_type": "SVGS",
	"country_code": "USA",
	"channel": "IPAY",
	"transaction_type": "DEPO",
	"priority": "NORM",
	"currency": "USD",
	"amount": 10.01
}

• sender_account_type and receiver_account_type allowed:
  • CARD: credit, debit, prepaid
  • CASH: cash in, cash out
  • LOAN: loan disbursement, loan repayment
  • SLRY: salary payment
  • TAXE: tax payment
  • SVGS: savings account transfer
  • VACC: virtual account transfer
  • OTHR: other types of transactions
• country_code is ISO 3166-1 alpha-3 code, in another words this will be like USA, BRA, IND etc.
• channel makes reference to environment used to transaction
  • IPAY: internet payment
  • PRSN: in-person
  • MOBI: mobile
  • ATM: ATM transaction
  • DICT: instant payment
  • CHCK: check
• transaction_type
  • TRAN: transfer
  • WITH: withdrawal
  • DEPO: deposit
  • PAYM: payment
  • RFND: refund
  • PRSN: in-person
• priority makes reference to how many time one transaction has to be settled. In general, instant payments systems using to URGT and HIGH.
  • URGT: urgent
  • HIGH: high priority
  • NORM: normal priority
• currency makes reference to the most used currency code by continent or worldly. In general, we used the main economies by continent or region.
  • South America: BRL, ARS
  • North America: USD, CAD
  • Europe: EUR, GBP
  • Asia: CNY, JPY, INR
  • Africa: ZAR, NGN
  • Oceania: AUD, NZD

Response:

{
	"risk_score": 4.92,
	"risk_factors": [
		"Transaction during business hours",
		"Sender name is extremely uncommon in Interpol data",
		"Receiver name is extremely uncommon in Interpol data",
		"High risk due to large economy size and high volume of transactions which can attract more fraudulent activities.",
		"Online transaction",
		"Transaction type: deposit",
		"High priority transaction",
		"Extremely common currency to transactions in world economy",
		"High transaction amount",
		"Urgent transaction with extremely high amount"
	],
	"transaction": {
		"datetime": "2026-02-18T10:59:59.999",
		"sender_name": "John Doe",
		"sender_account_type": "CASH",
		"receiver_name": "Joana Doe",
		"receiver_account_type": "SVGS",
		"country_code": "USA",
		"channel": "IPAY",
		"transaction_type": "DEPO",
		"priority": "HIGH",
		"currency": "USD",
		"amount": 10000.01
	}
}