Skip to main content
Version: 11.3.0

Risk-Signal Escalation Policy

Risk-signal escalation policy in HYPR Affirm is the mechanism by which risk signals the platform emits during a verification flow influence the flow's outcome. A platform-built policy evaluation engine reads those signals through administrator-authored rules and produces a Pass / Fail outcome plus an action (Deny, …) for each verification action.

This page is the policy model + observability view. For the configuration UI walkthrough — building rules, predicates, kits — see Affirm Risk Policy Builder.

For the conceptual distinction between risk-signal escalation and approver-chain escalation, see Escalation.

Available in 11.3

The end-to-end risk-signal policy system — administrator UI, runtime evaluation, and the policy ledger surfaced in the Activity Log — is available in HYPR 11.3 and later.

The policy model​

A risk-signal policy has four moving parts:

  • Risk signals — platform-emitted observations attached to a specific verification action. Each action exposes a fixed set of signals (for example, the Phone Number / Email Verification action exposes Medium Verified and Contact Preference; the IDV Outcome action exposes 81 signals across First and Second Biometric Check groups). Signals are not authored by administrators — they are the runtime telemetry the platform produces.
  • Predicates — administrator-authored boolean expressions over an action's risk signals. A predicate combines conditions (signal operator value) using AND / OR groups, nested arbitrarily.
  • Rules — ordered Pass / Fail rules. Each rule pairs a predicate with a result. If the result is Fail, the rule also carries an action (Deny, etc.) that decides what happens to the verification.
  • Policy Evaluation Kits — the persisted unit administrators publish. A kit defines rules for every verification action and is assigned to one or more verification flows. Each kit comes with built-in defaults so administrators customize rather than start from scratch.

For the predicate language, the rule editor UI, and signal lists per action, see Affirm Risk Policy Builder.

How policy evaluation runs​

When a verification action executes, the engine reads the action's risk signals from the runtime telemetry, walks the kit's rules in order, and stops at the first rule whose predicate matches. That rule's result determines the action's outcome:

  • A matching Pass rule lets the verification flow proceed to the next action
  • A matching Fail rule terminates the action with the rule's assigned action (Deny, …) — see the kit's per-rule configuration for the action set
  • If no rule matches, the action takes the kit-defined default behavior

Rule ordering is significant. The first match wins, so more specific failure rules are typically placed above broad pass rules.

The policy ledger​

Every verification flow that runs against an assigned kit produces a policy ledger — a per-flow audit of every rule the engine evaluated, every signal that matched, and the action taken. The ledger is preserved alongside the verification record itself.

The ledger lets compliance and support reconstruct why a verification produced its outcome at the rule and signal level — not just "the flow was denied," but "the IDV Outcome action's Secondary Not Clear rule fired because Dual Document EQ true AND Overall Result NEQ CLEAR."

Where policy decisions surface​

SurfacePolicy data
Activity LogPer-flow row shows the final Decision; the per-flow detail view appends the policy ledger as part of the verification record
Audit TrailAFFIRM_ESCALATION_* lifecycle events for each policy-driven decision
Affirm APIThe policy ledger is retrievable both as part of a verification's Activity Log entry and standalone for a given flow ID — useful for SIEM ingestion or compliance pipelines
ScorecardsAggregated escalation reasons per approver / requester for compliance review

See Observability and Verification Flow ID for how the policy ledger correlates with the rest of Affirm's observability surfaces via the Verification Flow ID.

Assigning a policy to a workflow​

A kit is inert until assigned. Open the verification flow's editor, navigate to Advanced Customization → Risk Policy, and pick the kit from the Policy Evaluation Kit dropdown. See Creating and Managing Verification Flows → Advanced Customization.

Workflows without an assigned kit fall back to platform default behavior.

Configuration via API​

Kits can also be authored and assigned via the Affirm API as an alternative to the Risk Policy Builder UI. The API exposes the kit schema (rules, predicates, signals, actions) and the per-workflow assignment. See the HYPR Affirm API for endpoint details.