Transaction Risk Score Computation Prompt Template

This prompt computes a structured risk score for a pending transaction by analyzing transaction features, entity profiles, behavioral signals, and historical patterns. It is designed for fraud engineers, security operations teams, and risk platform builders who need a model-generated risk assessment that includes feature-level attribution, confidence bounds, and a clear threshold comparison. Use this prompt when you need an explainable risk score that a downstream reviewer or automated system can act on.

Do not use this prompt as a standalone decision engine. The output should feed into an existing risk pipeline with human review gates for high-score transactions, not replace your rules engine or ML model. This prompt works best when you can supply structured transaction context, entity history, and a defined risk threshold policy. It assumes you have already extracted and normalized the transaction features before calling the model. The prompt is not a substitute for a calibrated statistical model and should not be the sole arbiter of transaction blocking or approval.

Before integrating this prompt, ensure your pipeline can supply the required inputs: a structured transaction payload, an entity profile with historical activity, and a defined risk policy with clear thresholds. After receiving the output, validate the JSON structure, check that the risk score falls within the expected 0-100 range, and route scores above your defined threshold to a human review queue. Log every score, attribution, and override decision for auditability. If the model returns malformed JSON or missing required fields, use a repair prompt or fall back to a rules-based score.

This prompt template is designed for fraud and security engineers who need to compute a risk score for a pending transaction. It is structured to accept a JSON payload of transaction features and entity context, producing a risk score with feature-level attribution, confidence bounds, and a threshold comparison. The output is designed to be machine-readable for automated decisioning and human-readable for downstream review queues. Use this template when you need an explainable, auditable risk decision, not a simple pass/fail flag.

textCopy
You are a transaction risk scoring engine. Your task is to analyze the provided transaction and compute a structured risk score.

## INPUT
[TRANSACTION_FEATURES_JSON]
[ENTITY_CONTEXT_JSON]

## CONSTRAINTS
- Do not hallucinate features not present in the input.
- If a feature is missing or null, note it in the `missing_features` list and do not use it in scoring.
- Your confidence must reflect the completeness and quality of the input data.
- Apply the following risk threshold policy: [RISK_THRESHOLD_POLICY].

## OUTPUT_SCHEMA
You must respond with a single JSON object conforming to this schema:
{
  "transaction_id": "string",
  "risk_score": "number (0.0 to 1.0)",
  "confidence_interval": {
    "lower_bound": "number",
    "upper_bound": "number"
  },
  "feature_attribution": [
    {
      "feature": "string",
      "contribution": "number (positive or negative)",
      "reasoning": "string"
    }
  ],
  "threshold_comparison": {
    "threshold": "number",
    "breached": "boolean",
    "severity": "string (LOW | MEDIUM | HIGH | CRITICAL)"
  },
  "recommended_action": "string (APPROVE | REVIEW | ESCALATE | BLOCK)",
  "explanation": "string (plain-language summary for a human reviewer)",
  "missing_features": ["string"],
  "model_confidence": "number (0.0 to 1.0)"
}

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## INSTRUCTIONS
1. Parse the input JSON. Identify all available features.
2. Compute a base risk score from the features.
3. Adjust the score based on entity context (e.g., user history, device reputation).
4. Calculate a confidence interval based on data completeness and feature reliability.
5. Compare the final score against the provided threshold policy.
6. Generate the structured output. Ensure all fields are present.

To adapt this template, replace the square-bracket placeholders with real data before sending it to the model. [TRANSACTION_FEATURES_JSON] should be a stringified JSON object containing the raw transaction data (amount, currency, merchant, location, etc.). [ENTITY_CONTEXT_JSON] should contain aggregated context about the user, device, and merchant, such as historical velocity, chargeback rate, and account age. [RISK_THRESHOLD_POLICY] defines the thresholds for REVIEW, ESCALATE, and BLOCK actions. [FEW_SHOT_EXAMPLES] should be replaced with 2-3 correctly formatted input-output pairs that demonstrate the desired scoring behavior, especially for edge cases like high-value transactions or new accounts. For high-risk production use, always combine this prompt with a post-generation validation step that checks the output JSON against the schema and verifies the score is within the [0,1] range before any automated action is taken.

This prompt is not a standalone widget; it is a scoring function inside a larger decision pipeline. The typical integration pattern places this prompt after feature extraction and before an escalation or auto-decision gate. Feature vectors—transaction amount, velocity, device fingerprint, geolocation mismatch, merchant category, and historical chargeback rate—should be assembled by upstream services and passed into the prompt as structured [CONTEXT]. The model's output is then parsed, validated, and fed into a rules engine or queue router. Do not call this prompt directly from a customer-facing endpoint without a surrounding harness that enforces timeouts, retries, and fallback scores.

Validation and retry logic: Parse the model's JSON output immediately and validate it against a strict schema. At minimum, confirm that risk_score is a number between 0 and 1, confidence_interval contains lower and upper bounds, and feature_attribution is a non-empty array of objects with feature, contribution, and evidence fields. If parsing fails or the schema is violated, retry once with an augmented prompt that includes the raw output and a specific error message (e.g., 'The previous output was missing the required confidence_interval field. Return valid JSON only.'). After a second failure, log the raw output, emit an alert, and fall back to a heuristic score computed from the same feature vector. Never pass an unvalidated score downstream.

Model choice and latency budget: This prompt benefits from models with strong reasoning and structured output capabilities. In production, target a model that supports JSON mode or structured output constraints natively to reduce parsing failures. Set a strict latency budget—typically 500–800 ms for a synchronous scoring call—and use a model that consistently meets that budget under your peak load. If latency exceeds the budget, consider a smaller model with a cached system prompt or pre-computed feature explanations. For high-throughput streams, batch scoring with asynchronous workers is preferred over blocking the transaction flow.

Logging, review, and audit trail: Log every prompt request and response pair, including the model version, latency, retry count, and validation outcome. Attach the transaction ID and the final risk score to your application logs so that downstream reviewers can trace any score back to its inputs and model output. For transactions that exceed your risk threshold and trigger a human review, include the full feature_attribution and explanation fields in the review queue payload. This gives fraud analysts the context they need to accept or override the score without re-running the prompt. Store these logs for at least the duration required by your compliance or chargeback dispute window.

Calibration and eval loop: Before deploying a new prompt version, run it against a golden dataset of historical transactions with known outcomes (fraud confirmed, chargeback received, or cleared). Measure calibration error—how well the predicted risk score aligns with observed fraud rates—and track drift over time. If the prompt's scores begin to diverge from actual outcomes, trigger a review of the feature definitions, the prompt's weighting language, or the underlying model. This eval loop should run offline, not in the hot path, and its results should gate promotion to production.