Skip to main content
Version: 11.3.0

Risk-Signal Escalation Policy

Risk-signal escalation policy in HYPR Affirm lets the risk signals that the platform emits during a verification flow influence the flow's outcome. The platform's policy evaluation engine applies administrator-authored rules to those signals and produces a Pass or Fail result for each verification action. A Fail result also carries a failure action: Deny, Escalate immediately, Redirect immediately, Continue on failure (escalate) or Continue on failure (deny at end).

This page describes the policy model and where policy decisions appear. To build rules, predicates and kits in the configuration UI, 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, including the administrator UI, runtime evaluation and the policy ledger in the Activity Log, is available in HYPR 11.3 and later.

The Policy Model​

A risk-signal policy has the following 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 71 signals in the General, Document 1 and Document 2 groups). Administrators do not author signals; signals are the runtime telemetry the platform produces. Kit rules can use only some of these signals, on the actions whose rules a kit can edit.
  • Predicates: Boolean expressions over an action's risk signals. A predicate combines conditions (signal operator value) using AND and OR groups, nested to any depth. Administrators author predicates for the actions whose rules a kit can edit; other actions keep built-in predicates.
  • Rules: Ordered Pass or Fail rules. Each rule pairs a predicate with a result. If the result is Fail, the rule also carries a failure action that decides what happens to the verification.
  • Policy Evaluation Kits: The persisted unit administrators publish. A kit sets, for each verification action it can configure, the rules, the retry budget or the failure actions, depending on the action. A kit is assigned to one or more verification flows. Each kit comes with built-in defaults, so administrators customize existing rules rather than writing every rule.

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, evaluates 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 lets the requester retry while the action's retry budget allows, then applies the rule's failure action
  • If no rule matches, the action passes and the verification flow proceeds

Rule ordering is significant. The first match wins, so place more specific Fail rules 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. For how HYPR handles verification data, see the HYPR Privacy Policy.

The ledger lets compliance and support teams reconstruct why a verification produced its outcome, at the rule and signal level. For example, instead of "the flow was denied," the ledger shows that "the Location action's Location Fail — Country Block List rule fired because the requester's country is on the block list."

Where Policy Decisions Surface​

The following table lists where policy data appears.

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_WORKFLOW_CHAT_ESCALATION events when a policy decision escalates the verification to live chat
Affirm APIThe policy ledger for a given Workflow ID

For how the Workflow ID links the policy ledger to the rest of Affirm's observability surfaces, see Observability and the Workflow ID.

Assigning a Policy to a Workflow​

A kit takes effect only when it is assigned to a verification flow, from the Policy Evaluation Kit drop-down under the flow's Advanced Customization > Risk Policy. Workflows without an assigned kit fall back to platform default behavior. For the steps, see Assigning a Kit to a Verification Flow.

Configuration via API​

You can also author and assign kits with the Affirm API instead of 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.