Skip to main content

Fraud & Risk Add-on Enablement

This page is how the Fraud & Risk Add-on for Agentic Payments is enabled on a running AxonFlow Enterprise deployment, and what is planned for packaged delivery. It assumes a working Enterprise deployment; see self-hosted deployment for standing one up.

Enterprise add-on

The Fraud & Risk Add-on for Agentic Payments is a separately priced add-on to AxonFlow Enterprise. It is not included in the base Enterprise license, the Evaluation tier, or the source-available Community edition. This page describes platform v11.1.0. The add-on is currently available through the early-access program.

Upgrading from v10: two variables now refuse boot

AXONFLOW_FINCRIME_SCORER_URL and AXONFLOW_FINCRIME_SCORER_TIMEOUT_MS configured the v10 scorer integration. From v11.0.0 the agent refuses to start while either is set to any non-empty value, and the refusal names the replacement. Remove them, and configure scoring with AXONFLOW_FINCRIME_RISK_FACT_URL and AXONFLOW_FINCRIME_RISK_FACT_TIMEOUT_MS as described below. A v10 Enterprise compose file set the timeout to a non-empty default, so check for it.

What runs where​

The add-on has two runtime components with different footprints:

  • The FinCrime Policy Pack runs inside the AxonFlow agent, as a typed policy document the v11 decision engine evaluates. No additional infrastructure is required for it.
  • The advisory risk scoring service is a separate service on its own container image, running inside your deployment next to the platform. It loads a model bundle and exposes an internal scoring endpoint plus a health endpoint, and the agent authenticates to it with the deployment's internal service secret. Transaction context is evaluated inside your deployment and is not sent to any third-party service.

The scoring service is stateless per request, so it scales horizontally behind its internal endpoint.

Step 1: install the FinCrime pack​

A deployment installs the pack by naming it in AXONFLOW_POLICY_PACKS on the agent:

AXONFLOW_POLICY_PACKS=fincrime

The value is a comma-separated list of pack names. It is deployment-wide: the pack composes onto every organization's policy root, and there is no per-organization switch. An organization cannot remove the pack by publishing its own document, but it can replace an individual control, as the pack reference explains.

The agent refuses to start, and names the reason, when:

  • the agent is not an Enterprise build. The pack is an Enterprise add-on, and any other build carries none;
  • a name is unknown or repeated;
  • the deployment declares no interactive realm, where a person can answer an approval. The pack's hold controls name an approver pool, and with no such realm the pool would name nobody, so boot is refused with POLICY_PACK_NO_APPROVER_REALM.

The pack's hold controls hold a request as a pending approval. A hold needs an Enterprise licence that carries the human-approval entitlement. Without it, a step-up is refused with reason approval_required and nothing is queued.

Step 2: wire the risk scoring service (optional)​

The pack's deterministic controls work without the scoring service. The scoring service adds one control: an advisory score threshold that holds a transaction for review. The score never blocks.

During early access, the scoring service image and its model bundle are provided by your AxonFlow contact as part of onboarding. They are not yet part of the standard install image set; see Planned packaging.

Scoring is wired to the platform with two environment variables on the AxonFlow agent:

VariableDefaultMeaning
AXONFLOW_FINCRIME_RISK_FACT_URLemptyThe scoring service's base URL, as an absolute http or https URL. The agent calls POST <URL>/v1/score. Empty means no scoring service is configured, which is the default: the score control then never applies, and each decision on which the pack is active records the status unconfigured.
AXONFLOW_FINCRIME_RISK_FACT_TIMEOUT_MS100The per-call budget in milliseconds, a whole number from 1 to 10000. A call that exceeds it is abandoned, the decision proceeds without a score, and the record states timeout.

The agent refuses to start when:

  • AXONFLOW_FINCRIME_RISK_FACT_TIMEOUT_MS is set without AXONFLOW_FINCRIME_RISK_FACT_URL: a budget with no service to call configures nothing;
  • the URL is not an absolute http or https URL, or the budget is not a whole number in range;
  • the URL is set and AXONFLOW_INTERNAL_SERVICE_SECRET is missing or shorter than 32 characters. Every score request would be refused by the scoring service, so no transaction would ever be scored;
  • either variable is set on a Community build. The scoring integration is an Enterprise add-on.

The agent authenticates to the scoring service with the deployment's internal service secret (AXONFLOW_INTERNAL_SERVICE_SECRET), which must be set to the same value on the agent and on the scoring service. The scoring service accepts no fallback credential.

Verify it is working​

The pack first. After installing the pack, send a canary decision request carrying a fincrime transaction context with an amount of 12000 and confirm the verdict is deny, attributed first to pack:fincrime:fincrime__high__value__amount__cap in the decision's evaluated_policies.

Then the scoring service. Its health endpoint (GET /health) is unauthenticated by design. It returns HTTP 503 while no model bundle is loaded, which is the usual first-bring-up failure. Once a bundle is loaded, it reports the model's identity (example response, abridged):

{
  "status": "ok",
  "model_id": "fincrime-fraud",
  "model_version": "0.1.0",
  "dataset": "sparkov-credit-card-fraud",
  "threshold": 0.011592,
  "scored_total": 3182,
  "auth_failures_total": 0
}

The threshold here is the scoring service's own reported operating point. AxonFlow does not use it; the pack's control decides against its own threshold (see Choosing an operating point).

Then the agent's view. On an Enterprise build the agent's /health carries a risk_score_fact member. It is {"status": "unconfigured"} when no URL is set. Otherwise it reports status (ok, or degraded while the last call was refused for authentication), last_outcome, outcomes_since_boot (a count per outcome) and budget_ms.

Finally, end to end from the audit side. Send a decision request carrying a fincrime transaction context and read the resulting decision record, for example through the Decisions API. Its policy_details.fincrime_risk_score should have status: "scored" and a score; the risk scoring page lists every field and status.

Signals worth alerting on:

  • auth_failures_total climbing on the scoring service's health endpoint, status: "degraded" in the agent's risk_score_fact, or decision records with status auth_rejected: the agent and the scoring service disagree on the internal service secret. Because a missing score never blocks a request, this degrades scoring silently from the decision path's point of view. These signals exist to make it visible.
  • Decision records with status timeout, unavailable or malformed_response: calls are timing out, failing, or returning something the agent cannot read. The decision path is behaving as designed (the deterministic controls still apply), but you are not getting scores. The agent also exports the counter axonflow_fincrime_risk_fact_total by outcome.

Choosing an operating point​

The score control holds a transaction when its score is at or above the pack's threshold. To move that threshold for your organization, publish a copy of the control under its own id; see tuning the score threshold.

The scoring service also reads AXONFLOW_FINCRIME_SCORER_THRESHOLD (a value from 0 to 1). It changes only the threshold and above-threshold flag the scoring service reports about itself. It does not change what AxonFlow decides: the agent reads only the score. Leave it unset unless you are running calibration exercises against the scoring service directly.

Planned packaging​

Two delivery improvements are planned, with no dates committed here:

  • License-based entitlement: enablement gated by an add-on entitlement carried in your Enterprise license, rather than by deployment configuration.
  • Packaged image delivery: the scoring service as an optional image in the standard install flow (a digest line and an optional service alongside the existing image set), versioned and upgraded like the rest of your deployment; see deployment operations for how the existing image set is managed.

Until then, the early-access path above is the supported way to run the add-on.

Last updated on