Risk Scoring API

POST /v1/risk/score is Sentra's primary online integration point. It accepts transaction, entity, optional KYC/KYB references, and optional online feature overrides. It returns a 0-1000 risk score, a decision action, explainability reasons, evidence, model version, LLM version, request ID, latency, and AI enrichment status.

Endpoint

POST /v1/risk/score
Authorization: Bearer <token>
Content-Type: application/json

Required role: Analyst or Admin.

Request shape

type RiskScoreRequest = {
  transaction: {
    tx_id: string;
    created_at: string;
    amount: number | string;
    currency: string;
    direction: string;
    channel: string;
    psp: string;
    route_id: string;
    status: string;
    status_reason: string;
    fee_total: number | string;
    fx_rate?: number | string;
  };
  entities: {
    user_id?: string;
    merchant_id?: string;
    sender_entity_id: string;
    receiver_entity_id: string;
    sender_country: string;
    receiver_country: string;
    ip_hash?: string;
    device_id_hash?: string;
  };
  kyc_refs?: Array<{
    entity_id: string;
    doc_hash?: string;
    doc_s3_url?: string;
    text_blob?: string;
  }>;
  feature_overrides?: Record<string, number>;
};

Required transaction fields

Entity fields

KYC/KYB references

kyc_refs are optional. When present, Sentra persists the document reference and uses it for asynchronous AI enrichment.

Use:

• doc_hash when you already have a stable hash.
• doc_s3_url when the document is stored in sentra-kyc-docs or another approved bucket.
• text_blob only when retention and masking policy allows copied text.

Feature overrides

feature_overrides lets the platform send model features that are available online but not part of the small base request body.

Examples:

{
  "feature_overrides": {
    "response_time_ms": 117,
    "duplicate_order_count": 2,
    "merchant_hour_error_rate": 0.08,
    "is_extreme_amount": 1
  }
}

The active model aligns incoming fields using feature_schema.json. Extra fields are ignored, and missing engineered fields are filled with 0.0.

Response shape

type RiskScoreResponse = {
  risk_score: number;
  decision: "PASS" | "REVIEW" | "HOLD" | "BLOCK";
  reasons: string[];
  evidence: Array<{
    source: string;
    key: string;
    quote?: string;
    span?: string;
  }>;
  model_version: string;
  llm_version: string;
  request_id: string;
  latency_ms: number;
  llm_status: "pending" | "ready";
};

Persistence side effects

Each scoring request:

1. Upserts sender and receiver entities.
2. Upserts the transaction.
3. Persists KYC/KYB references when present.
4. Persists a risk_scores row.
5. Ensures a case exists when the decision is REVIEW, HOLD, or BLOCK.
6. Queues an LLM job when KYC/KYB refs exist and no cache is ready.

Latency contract

The scoring endpoint should return quickly. The LLM enrichment path is intentionally asynchronous, so llm_status: "pending" is a valid successful response.