Fraud output contract¶
Canonical partner publication
This file is the canonical partner copy. Service-repo mirrors must sync from here (see internal Engineering → Contract sources).
This page describes what the fraud report step accepts from the scoring services, how it turns a prediction into a dashboard report, and the payload it delivers to the banking application.
Two open issues affect this contract
- The risk tiers are incompatible. The ML scoring service and the report step use different tier labels and score boundaries. Some ML predictions are rejected and produce no dashboard report. See Risk tiers: producer and consumer disagree. This is a product defect awaiting an owner decision; this page does not choose the fix.
- The decision policy is provisional. The automated
decision(approve|pend|block) andescalationscome fromfraud-decision-v1. That policy is provisional and has no production or compliance sign-off. The language model never makes the decision; Python policy code does.
Documentation status
Last verified: 26 Sep 2026. Contract behaviour follows the status vocabulary. Confirm the revision in your environment with MasteryHive.
Pipeline¶
transaction event → baseline checks → lastCheckReport
→ ML scoring (/call-and-predict) or rule scoring (/rule_based_engine)
→ report message → report step (/report)
→ validate → normalise score and category → derive evidence → apply policy
→ narrative (aiSummary only) → POST {backend}/transaction/create-report
| Report field | Produced by |
|---|---|
fraudScore, riskCategory |
Deterministic normalisation (code) |
indicatorRecords, aiChecks, reasonCodes |
Deterministic evidence derivation (code) |
decision, escalations |
Policy fraud-decision-v1 (code, provisional) |
fraudIndicators, aiRecommendation |
Views derived from the structured decision, kept for dashboard compatibility |
aiSummary |
Language model, or a deterministic fallback if the model call fails |
provenance |
Contract, policy and narrative versions plus a hash of the prediction |
The contract version is fraud-output-v3, the policy version fraud-decision-v1, and the narrative version gemini-summary-v1. All three are carried in provenance.
Which engine produced the prediction¶
The report step identifies the engine from the envelope's check_type (ml_check or rule_based_check) plus the prediction's keys:
- ML is identified by
probability_score. - Rule is identified by
flaggedandscoretogether. predicted_levelappears in both, so it does not identify the engine.
| Condition | Result |
|---|---|
| ML keys and rule keys in the same prediction | Rejected: AMBIGUOUS_PREDICTION_CONTRACT |
check_type says one engine, keys say the other |
Rejected: CHECK_TYPE_MISMATCH |
No recognised check_type (missing, empty or any other value) and no identifiable shape |
Rejected: AMBIGUOUS_PREDICTION_CONTRACT |
A rejected prediction produces no report. The report step answers the delivery with HTTP 400, and the message is retried and eventually dead-lettered.
Input validation¶
TransactionEvent¶
Validated on the checks service for baseline checks.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | Transaction UUID |
time |
string | yes | HH:MM:SS |
date |
string | yes | YYYY-MM-DD |
amount |
float | yes | |
currency |
string | yes | For example NGN |
description |
string or null | no | |
type |
string or null | no | For example bill payment |
device |
string or null | no | |
device_type |
string or null | no | For example Online |
balance |
float or null | no | Account balance after the transaction |
channel is not a TransactionEvent field.
lastCheckReport¶
The minimum structure for ML scoring, validated as LastCheckReportInput.
| Field | Required | Notes |
|---|---|---|
id |
yes | Report id |
customerProfileId |
yes | |
temporalChecks.prediction |
no (defaults to {}) |
Flat dictionary of boolean anomaly flags |
transactionChecks.prediction |
no | |
locationChecks.prediction |
no | |
*LastProcessedDate |
no | Date strings |
createdAt |
no |
ML prediction: what the scoring service emits¶
| Field | Type | Description |
|---|---|---|
probability_score |
float, 0 to 1 | 1.0 when a critical feature fires (a blacklist or watchlist match). Otherwise the sum of the highest triggered weight in each tier group, divided by the maximum possible, capped at 0.9 |
predicted_level |
string | Critical Risk (score >= 1.0), High Risk (> 0.70), Mid Risk (> 0.30), Low Risk otherwise |
interpretation |
object | Human-oriented explanation per check. Not used for evidence or policy |
observations |
object | Per-check {status, description} flags |
ML prediction: what the report step accepts¶
| Field | Rule |
|---|---|
probability_score |
Float between 0 and 1 |
predicted_level |
One of Low Risk, Mid Risk, High Risk. Critical Risk is not accepted |
| Agreement | predicted_level must equal the report step's own band for the score: High Risk if > 0.66, Mid Risk if > 0.33, otherwise Low Risk. A mismatch is rejected with ML_SCORE_TIER_CONFLICT; the report step does not recompute or correct the label |
ML → dashboard normalisation (accepted predictions only)¶
fraudScore = round(probability_score × 100) # Python round(): halves go to the even number
riskCategory = high if probability_score > 0.66
= medium if probability_score > 0.33
= low otherwise
Risk tiers: producer and consumer disagree¶
The two sides above do not agree. For the scoring service's own output, the report step behaves as follows:
| Scoring service output | Report step result |
|---|---|
Critical Risk, score 1.0 |
Rejected (label not accepted) |
Score in (0.66, 0.70], labelled Mid Risk |
Rejected (ML_SCORE_TIER_CONFLICT: the report step requires High Risk) |
Score in (0.30, 0.33], labelled Mid Risk |
Rejected (ML_SCORE_TIER_CONFLICT: the report step requires Low Risk) |
Score in (0.70, 0.90], High Risk |
Accepted |
Score in (0.33, 0.66], Mid Risk |
Accepted |
Score <= 0.30, Low Risk |
Accepted |
What this means for integrators:
- A 200 from ML scoring does not mean a report will follow. Critical (blacklist or watchlist) outcomes and the two boundary bands currently produce no dashboard report.
- Reconcile scoring responses against received reports by
transactionId, and treat a scored transaction with no report after your agreed interval as an incident. - This site does not choose between the possible fixes (align the report step to the scoring service, align the scoring service to the report step, or translate at the boundary). The owners have not yet decided.
The rule engine labels its own predicted_level with > 0.70 / > 0.30. The report step does not validate that label (see below), so rule predictions are not rejected, but the level in the rule response and the category on the dashboard report can differ.
Rule prediction output¶
| Field | Type | Description |
|---|---|---|
flagged |
bool | Whether any rule matched |
score |
float, 0 to 1 | Rule severity score |
passed_conditions |
list | Condition trees whose predicate did not match |
failed_conditions |
list | Condition trees whose predicate matched |
predicted_level |
Low Risk, Mid Risk or High Risk |
Advisory label from the rule engine. Ignored for engine identity and for riskCategory |
Rule → dashboard normalisation¶
fraudScore = round(score × 100)
riskCategory = low if flagged is false
= high if flagged and score >= 0.66
= medium if flagged and score < 0.66
The high band is inclusive (>= 0.66) on the rule path and exclusive (> 0.66) on the ML path. A flagged rule score of 0.659 rounds to fraudScore 66 with riskCategory medium.
Unflagged rule results map to riskCategory = low with reason RULE_NOT_FLAGGED. Do not compare a rule fraudScore with an ML fraudScore as if they measured the same thing.
Evidence and labels¶
indicatorRecordsuse stable codes (for exampleBLACKLISTED_LOCATION_TRANSACTION), andfraudIndicatorsis the list of their labels.severityis set only when the code carries a known signal: codes startingBLACKLISTED,SANCTIONS,KNOWN_FRAUD,SAR_orUNUSUALare high; codes startingHIGHorLARGEare medium. Unknown codes, including rule-condition UUIDs, omitseverityrather than defaulting tolow.aiCheckshas one item per observation or rule condition. Itsstatusistriggered(the observation is true, or the rule predicate matched) ornot_triggered. The producers'passed/failedwording is kept only inrawAnalysisResponse.- Rule labels describe the rule in business language (for example
Transaction amount exceeds 5,000,000), and details separate the observed value from the threshold. Currency symbols are not invented when the envelope has no currency. A missing observed value is reported asactual value was unavailable, never as a silent pass.
Decision policy (fraud-decision-v1, provisional)¶
The primary decision is exactly one of approve, pend or block. Escalations (investigator_review, sar_review) are separate.
riskCategory |
Primary decision | Escalation |
|---|---|---|
low |
approve |
none |
medium |
pend |
none |
high |
block |
investigator_review if any indicator triggered |
Named overrides (to be confirmed by compliance):
| Signal | Effect |
|---|---|
BLACKLISTED_* |
At least pend |
SANCTIONS_* / KNOWN_FRAUD_* |
At least block |
SAR_* / SAR_TRIGGER |
Adds sar_review |
A blacklist match can never produce approve, and adding an indicator can never lower the primary decision. Escalation labels are labels on the report; they are not regulatory filings.
Dashboard payload (AIReportResponse)¶
Delivered to POST {backend}/transaction/create-report with Authorization: ApiKey <jwt> and x-tenant-id (see Auth and tenancy).
| Field | Type | Source |
|---|---|---|
transactionId |
UUID | Report message envelope |
aiSummary |
string | Language model or deterministic fallback |
fraudScore |
int, 0 to 100 | Normalisation |
riskCategory |
low, medium or high |
Normalisation (from the score, never from the model) |
fraudIndicators |
list of strings | Labels derived from indicatorRecords |
indicatorRecords |
list of FraudIndicator |
Stable code, label and source; severity only when authoritative |
aiRecommendation |
list of strings | [decision] followed by the escalations |
decision |
approve, pend or block |
Policy |
escalations |
list of investigator_review / sar_review |
Policy |
reasonCodes |
list of strings | Policy and evidence codes |
aiChecks |
list of FraudCheckResult |
status is triggered or not_triggered |
provenance |
object | Contract and policy versions, prediction hash, source score |
rawAnalysisResponse |
object | The full report message |
timestamp |
string | Server time |
Errors the report step can raise¶
| Code | Meaning |
|---|---|
AMBIGUOUS_PREDICTION_CONTRACT |
Both engine shapes present, or neither identifiable |
CHECK_TYPE_MISMATCH |
Declared check_type contradicts the prediction's keys |
UNKNOWN_CHECK_TYPE |
Defined but not currently raised: an unrecognised check_type is treated as undeclared, and the engine is identified from the keys |
ML_SCORE_TIER_CONFLICT |
ML predicted_level disagrees with the report step's band for the score |
| Validation error (no code) | A required field is missing, or a value is outside the allowed set (for example Critical Risk) |
All of them stop the report. The message is answered with HTTP 400 and no dashboard report is delivered.