Flows and Resolution

A fraud decision does not come from a fixed rule set — it comes from the flows you publish. You scope a flow by operation type (card payment, bank transfer, wallet withdrawal…); when a decision request arrives the system resolves every matching published flow, runs them and merges the results into a single decision.

This page explains how resolution works — the answer to "which flows did my request land on?". For the endpoint contract see Decision API.

The endpoint that triggers your rules

The flow you published — and the rules inside it — are triggered by a single call:

POST /api/v1/fraud/decisions/evaluate
Authorization: Bearer <access-token>

You mint the token from POST /api/v1/auth/token with your Ed25519 signature. Required scope: fraud:view_decisions. Full field dictionary: Decision API.

Which request field drives which dimension

You steer the resolution — which flows run is derived from what you send:

curl -X POST "https://api-gateway.lunixi.com/api/v1/fraud/decisions/evaluate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bankTransfer": { "amount": 250000, "currency": "TRY", "iban": "TR33…" },
    "customer": { "id": "cust_84213" },
    "productContext": "direct_api"
  }'

This call finds every flow you scoped to the bank_transfer operation type, runs them and returns the merged decision. Which flows ran and which rules matched come back in the explainability fields and the multiFlow block — that is where you read why the decision was made.

The dimensions a flow is scoped on

A flow can be narrowed on the dimensions below. A dimension left empty means "any" — it matches every value on that axis.

subjectType carries the operation type: card_payment · bank_transfer · eft · fast · crypto_transfer · wallet_deposit · wallet_withdrawal · wallet_payment · wallet_transfer · bill_payment · loan · payout · refund · cash_in · cash_out · international_transfer

Resolution: every matching flow runs

The scope dimensions are unchanged — merchantId · merchantGroupIds · flowType · subjectType · integrationMode · productContext (an empty column matches everything). What changed is the selection step: the system no longer picks the single narrowest flow. Every published flow that passes the filter is resolved and runs in one of two lanes, chosen by its executionMode: sync flows produce the decision response, async flows run in the background without delaying the decision.

The sync lane: independent runs, one decision

Every executionMode='sync' flow runs independently on a zero base state: flow order does not affect the result, and no flow sees another flow's score or reason codes. Once they finish, the outcomes are merged into a single decision:

Three levels of time limit

The time budget is not one layer but three nested limits, and the outer one bounds the inner:

If a node sets its own timeoutMs it is used — but it cannot exceed the flow deadline; the node is bounded by whatever time is left.

The flowPath in the explainability output is now flow-prefixed: each step comes as flow:<flow-name>/<node-id> — you can read from the response which node belongs to which flow.

The async lane: never delays the decision

executionMode='async' flows do not hold up the decision response: the run is queued, shows up in the response's asyncFlows list with status queued, and executes in the background on the same engine. The result is written to its run record — see Async result delivery below.

The multiFlow block in the response

The decision response gained an additive field — no existing field changed:

{
  "multiFlow": {
    "enabled": true,
    "executedFlows": ["card-velocity-rules", "device-reputation"],
    "skippedFlows": [
      { "name": "heavy-analysis", "reason": "budget_exceeded" }
    ],
    "asyncFlows": [
      { "name": "case-sweep", "status": "queued" }
    ]
  }
}

On the gRPC wire the same block travels as a JSON string in the multiFlowJson field.

Calling a specific flow by name

If the request carries a flow name in metadata, resolution locks onto that name — multi-flow resolution runs only the named flow for that request:

{ "metadata": { "fraudFlowName": "yuksek-riskli-havale" } }

Accepted keys: liveFraudFlowName, fraudFlowName, flowName. This is how you exercise canary or trial flows — do not use it to override the default in production.

Async result delivery

The result of an executionMode='async' flow is written to its run record.

Delivery of those results to you will run on platform webhook events — coming soon. For platform webhook setup, signature verification and retry behaviour, see Webhook setup.

Missing/malformed data in switch nodes: condition vs op

A switch case can be written in two forms, and their behaviour on missing or malformed operands (e.g. text where a number is expected) is deliberately different:

Flow-author rule: write decision-critical (block-side) checks with condition — you want fail-closed. Write cheap routing matches with op — missing data falls to default and stays visible via indeterminateCases.

Inbound webhook trigger (triggerType: webhook)

A webhook-triggered flow is fired from outside through an event-stream connection profile. The chain:

1. Define a connection profile in the panel (source: webhook; the signature secret lives on the profile).
2. The external system POSTs to POST /api/v1/fraud/database-events/{connectionProfileId}/webhook/{routingKey} — the signature travels in the x-event-signature header, the timestamp in x-event-timestamp.
3. The signature is verified (HMAC + time window); then every published flow whose triggerType is webhook or event and whose triggerConfig.webhookPath equals the routingKey is executed.

This inbound trigger only runs the flow; its signature secret lives on the connection profile.

Choosing an executionMode

When nothing matches

This is deliberate: the earlier behaviour could not tell an unconfigured merchant apart from an explicitly cleared payment. Watch the fraud.decision.unconfigured reason code while you integrate — you will see it in production if your flow never went live.

Capability bundles

Flows also run on their own, but there is a capability bundle layer above them: a bundle describes which capabilities run for a decision, in what order and under which failure policy, orchestrating several flows where needed.

Running your own code inside a flow

Rule nodes are enough to express a threshold or a comparison, but some policies cannot be written in a rule language — computing a score with your own formula, parsing an external response, a transformation specific to your business. For those you place a script node in the flow and run your own JavaScript.

Script asset lifecycle

How it runs

The code does not run inside the fraud service but in a separate execution service: inside a real V8 isolate (isolated-vm), with its own heap ceiling and its own time limit. Isolates are recycled after a set number of jobs, and output and log sizes are capped.

Two modes

Every execution is audited: success · failed · timeout. A script that exceeds its time ceiling does not stall the flow — it returns as an error and the flow's fail-closed posture takes over.

Related

• Decision API — the POST /api/v1/fraud/decisions/evaluate field dictionary
• Decision logs — GET /api/v1/fraud/decision-logs