Skip to main content

FinCrime Transaction Context Guide

FinCrime pack v3 governs payment operations declared by the deployment's trusted action registry. This guide describes the v3 contract. The v11.1.0 release still carries pack v2. A statement about payments or a fincrime_transaction key cannot declare an action; the admitted organization, client, and exact target select one. Other detector categories still inspect request content independently.

Where the objects ride​

Request surfaceCarrier
POST /api/v1/decidecontext.fincrime_transaction and context.fincrime_cohort
POST /api/v1/mcp/check-input, POST /mcp/resources/query, POST /mcp/tools/execute, MCP server check_policyparameters.fincrime_transaction and parameters.fincrime_cohort

The request target identifies the actual tool. For Decision API, use target.type: "tool", target.server, and target.tool. For MCP check-input and check_policy, the connector, tool, and operation identify the action. The registry lists each admitted organization and client separately. An undeclared operation on a registered payment server is denied, including when that server has entries only on another API plane. An unrelated server is outside the FinCrime pack, even if it quotes a payment in text or other parameters.

fincrime_transaction​

For execute, retry, and beneficiary_change, supply an object with these fields:

FieldTypeRequirement
versionJSON numberExactly 2
transaction_idnonempty stringStable payment identity
amountstringUnsigned plain decimal in major currency units, such as "250000"
amount_unitstringExactly "major"
currencystringUppercase supported ISO 4217 code configured in the registry
beneficiary_idnonempty stringStable payee identifier
payment_typestringtransfer, wire, or card
sender_location, receiver_locationstringsUppercase two-letter country code, optionally with a subdivision suffix
timestampstringRFC 3339 timestamp

A card payment also needs payment_method: "card_present" or "card_not_present". An optional merchant_category_code must be a four-digit string. A beneficiary change needs nonempty beneficiary_before and beneficiary_after, different from each other, with beneficiary_after equal to beneficiary_id. A retry needs retry_of equal to transaction_id, previous_state: "failed", and previous_amount, previous_currency, and previous_beneficiary_id equal to the present transaction. The payment service supplies those prior facts; AxonFlow validates consistency but does not fetch the ledger state.

Amounts accept digits and at most the currency's minor-unit precision. A JSON number, sign, exponent, negative value, unsupported currency, or amount_unit: "minor" is refused. The agent compares exact integer minor units with decimal major-unit thresholds configured for the same organization and currency. There is no FX conversion or default USD threshold.

fincrime_cohort​

Every monetary action supplies currency equal to the transaction currency, historical_mean_amount as a nonnegative major-unit decimal string, and txn_frequency_1h as a finite nonnegative integer JSON number. Frequency 10 or above adds a velocity approval fact; frequency 20 or above adds a cumulative-exposure approval fact. The integrating service computes these aggregates from its transaction stream.

Validation​

Missing, malformed, contradictory, or unconfigured required facts produce the typed pack:fincrime:fincrime__invalid__context__block constraint. The response denies the covered action and the audit records a stable reason. A missing cohort does not silently disable velocity review. investigate is permitted only as a declared MCP query and needs no transaction context; the connector remains responsible for honoring its read only contract.

Per-plane outcome semantics​

SurfaceDeny controlApproval requirement
Decision APIverdict: "deny"verdict: "needs_approval" with pending_approval
MCP request routesHTTP 403HTTP 403 with pending_approval
MCP server check_policyallowed: falseallowed: false with a pending approval

A held call does not run. The caller retries the exact call after a person approves, naming the approval via X-Axonflow-Approval-Id or approval_id. The retry is decided again. Changed input, target, principal, registry, or policy bundle requires a new approval. A deny control cannot be overridden by an approval. See pending approvals.

What consumes the objects​

The deterministic FinCrime detector computes typed facts from the selected action and validated fields. An optional advisory risk scorer receives only valid covered payment context. A returned score is a fact read by the typed policy, and can add a hold. A missing score never bypasses deterministic validation. policy_details.fincrime_decision records pack version, registry digest, action class, and invalid-context reason; policy_details.fincrime_risk_score records scoring status.

Serialization​

FinCrime v3 does not match serialized JSON or scan arbitrary MCP parameters to decide whether a payment exceeds a threshold. Send object-valued context with decimal strings and the exact field types above. Other platform detectors may still inspect request text for PII, prompt injection, SQL injection, or other categories.

Example Decision API context​

{
"stage": "tool",
"target": {"type": "tool", "server": "payments", "tool": "payments.create_transfer"},
"query": "Settle invoice",
"context": {
"fincrime_transaction": {
"version": 2,
"transaction_id": "tx-123",
"amount": "250000",
"amount_unit": "major",
"currency": "IDR",
"beneficiary_id": "payee-42",
"payment_type": "transfer",
"sender_location": "ID",
"receiver_location": "ID",
"timestamp": "2026-10-21T09:00:00Z"
},
"fincrime_cohort": {
"currency": "IDR",
"historical_mean_amount": "120000",
"txn_frequency_1h": 1
}
}
}

The deployment must register that exact action for the admitted organization and client, and configure IDR thresholds. An MCP request carries the same two objects under parameters and names its exact connector, tool, and operation. The stated amount is only a sample, not an implicit authorization. A covered execution still needs human approval below its configured cap.

Request authentication​

The organization and client come from the admitted credentials, never from fields in these context objects. Operators must scope the registry to those identities. The actor supplying cohort and prior retry facts must be trusted by the payment integration; the agent enforces their type and consistency, not their provenance from a payment ledger.