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 surface | Carrier |
|---|---|
POST /api/v1/decide | context.fincrime_transaction and context.fincrime_cohort |
POST /api/v1/mcp/check-input, POST /mcp/resources/query, POST /mcp/tools/execute, MCP server check_policy | parameters.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:
| Field | Type | Requirement |
|---|---|---|
version | JSON number | Exactly 2 |
transaction_id | nonempty string | Stable payment identity |
amount | string | Unsigned plain decimal in major currency units, such as "250000" |
amount_unit | string | Exactly "major" |
currency | string | Uppercase supported ISO 4217 code configured in the registry |
beneficiary_id | nonempty string | Stable payee identifier |
payment_type | string | transfer, wire, or card |
sender_location, receiver_location | strings | Uppercase two-letter country code, optionally with a subdivision suffix |
timestamp | string | RFC 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
| Surface | Deny control | Approval requirement |
|---|---|---|
| Decision API | verdict: "deny" | verdict: "needs_approval" with pending_approval |
| MCP request routes | HTTP 403 | HTTP 403 with pending_approval |
MCP server check_policy | allowed: false | allowed: 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.
