Policy Modes

A policy is the ruleset that converts a raw risk score into the final action returned by VertexY. You can read it with GET /risk-engine/policy and update it with PUT /risk-engine/policy without redeploying your integration.

The three modes

HYBRID (recommended for production)

The engine's recommendation is enforced. Your application should treat action as authoritative.

Flow:

1. VertexY receives the assess request.
2. The engine computes riskScore.
3. The score is compared with allowMaxScore and reviewMaxScore.
4. The same outcome is returned in both action and recommendedAction.

Default score thresholds:

1. allowMaxScore Default is 30. Valid range is 0 to 100.
2. reviewMaxScore Default is 75. Valid range is 0 to 100.

Scores above reviewMaxScore → block. The constraint allowMaxScore ≤ reviewMaxScore is enforced.

Use hybrid when you want VertexY to make real-time allow, review, and block decisions.

ADVISORY

The engine scores every transaction normally, but the action field is always allow regardless of the score. The true recommendation is available in recommendedAction.

Flow:

1. VertexY scores the request normally.
2. The engine computes the threshold-based recommendation.
3. The public action is forced to allow.
4. The true recommendation remains available in recommendedAction.

Use advisory when:

• Rolling out to a new market or user segment where you want to observe scores without affecting conversions
• Evaluating VertexY's accuracy against your existing fraud system before full cutover
• Compliance requires human review of all blocks (use recommendedAction to queue reviews)

SHADOW

Full scoring runs and is stored, but the response always returns action: allow and suppresses the reason codes. Designed for completely invisible evaluation.

Flow:

1. VertexY runs the full scoring pipeline.
2. The score and recommendation are stored internally.
3. The live response stays permissive with action: allow.
4. The response is marked as shadow-mode output.

Use shadow when:

• You want zero impact on your existing checkout flow while collecting a scoring baseline
• Comparing VertexY's model against a legacy system with no risk to live conversions
• Onboarding a new payment method or user cohort where you want to build a risk history first

Choosing the right mode

1. Production with real enforcement Use hybrid.
2. A/B test or soft launch Use advisory.
3. Data collection or baseline building Use shadow.
4. Post-incident investigation with no live blocks Use advisory.

Degraded mode

When one or more upstream services (graph, velocity score) become unavailable, the engine falls back to degraded mode rather than failing the request. You configure what action to take at minimum in these conditions.

Degraded flow:

1. VertexY checks whether the scoring dependencies are healthy.
2. If one dependency is missing, the engine continues with the remaining signal families.
3. The response includes degradation reason codes showing which subsystem was unavailable.
4. If the computed action is weaker than degradedMinAction, VertexY raises it to that minimum action.
5. Otherwise, VertexY returns the computed action unchanged.

degradedMinAction

The minimum action to return when any dependency is degraded. Defaults to allow. Values: allow | review | block.

Example: Set degradedMinAction: "review" to ensure that no transaction silently passes through when the graph service is down — all degraded-mode assessments will be flagged for manual review.

oneHopMinAction

The minimum action to enforce when the ONE_HOP_GUARD_TRIGGERED reason code fires. This is independent of overall degraded mode. Values: allow | review | block.

Example: Set oneHopMinAction: "review" to always queue for review any user who has a direct graph connection to a blocked entity, even if their personal score is low.

Updating your policy

curl -X PUT https://api.vertexY.com/api/risk-engine/policy \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "hybrid",
    "allowMaxScore": 30,
    "reviewMaxScore": 70,
    "degradedMinAction": "review",
    "oneHopMinAction": "review",
    "globalThreatPenaltyOverride": 25
  }'

await fetch("https://api.vertexY.com/api/risk-engine/policy", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "hybrid",
    allowMaxScore: 30,
    reviewMaxScore: 70,
    degradedMinAction: "review",
    oneHopMinAction: "review",
    globalThreatPenaltyOverride: 25,
  }),
});

All fields are optional — send only the ones you want to change. Every policy update is recorded in the audit log accessible from your dashboard.

Read the current policy

curl https://api.vertexY.com/api/risk-engine/policy \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"

Policy fields reference

1. mode Type is string. Allowed values are hybrid, advisory, and shadow. This controls the decision enforcement mode.
2. allowMaxScore Type is integer. Range is 0 to 100. Scores at or below this value return allow.
3. reviewMaxScore Type is integer. Range is 0 to 100. Scores above allowMaxScore and up to this value return review.
4. degradedMinAction Type is string. Allowed values are allow, review, and block. This sets the minimum action during service degradation.
5. oneHopMinAction Type is string. Allowed values are allow, review, and block. This sets the minimum action when the one-hop guard triggers.
6. globalThreatPenaltyOverride Type is integer. Range is 0 to 100. This overrides the global threat score penalty for the company.