Credit Scoring and Decisions Domain

Overview

This section covers the API-first scoring path that turns an active consent plus a computed evidence snapshot into a partner-visible credit decision. The US and JP surfaces both call the same scoring service helper, but they differ in how they shape the returned decision, how they handle missing callbacks, and how they publish downstream webhook payloads.

The integration is built around two callback targets: partner-specific overrides from PARTNER_SCORING_URLS, and the fallback scoring-orchestrator URL from SCORING_CALLBACK_URL. The partner override wins when it exists, the callback payload is normalized into a stable decision shape, and approved-limit and reason data are propagated to downstream consumers in the webhook path.

Architecture Overview

flowchart TB
  subgraph APISurfaces [API Surfaces]
    USScore[US score routes]
    JPScore[JP score routes]
    AuthGate[Partner auth gate]
  end

  subgraph ScoringService [Partner scoring service]
    FetchDecision[fetchScoringDecision]
    ConfigLookup[getPartnerScoringConfig]
    NormalizeDecision[normalizeDecision]
  end

  subgraph CallbackTargets [Callback targets]
    PartnerCallback[Partner specific callback]
    FallbackCallback[SCORING_CALLBACK_URL]
    ScoringOrchestrator[Scoring orchestrator]
  end

  subgraph Downstream [Downstream propagation]
    DecisionWebhook[Decision completed webhook]
  end

  USScore --> AuthGate --> FetchDecision
  JPScore --> AuthGate --> FetchDecision

  FetchDecision --> ConfigLookup
  FetchDecision --> NormalizeDecision

  ConfigLookup --> PartnerCallback
  FetchDecision --> FallbackCallback
  FallbackCallback --> ScoringOrchestrator

  USScore --> DecisionWebhook
  JPScore --> DecisionWebhook

Component Structure

Partner Scoring Service

apps/api/src/services/partner-scoring.ts

This service resolves the scoring callback target, sends the request, and normalizes the provider response into a stable ScoringDecision shape for the route handlers. It is the only piece that knows about partner-specific callback overrides and the fallback scoring URL.

ScoringDecision shape

Property Type Description
decision string Normalized decision outcome returned to the route handlers.
reasons string[] Normalized reason codes carried from the provider response or generated by the service.
approvedLimit `number \ undefined`
score `number \ undefined`

Provider callback payload shape

Property Type Description
score `number \ undefined`
decision `string \ undefined`
outcome `string \ undefined`
result `string \ undefined`
approved_limit `number \ undefined`
approvedLimit `number \ undefined`
reasons `string[] \ undefined`
reason_codes `string[] \ undefined`

Partner scoring configuration forms

Form Shape Behavior
String URL template string Replaced with encodeURIComponent(applicantId) when it contains {applicantId}. If that token is present, the request is sent as GET; otherwise it is sent as POST.
Object config `{ url: string; method?: "GET" \ "POST" }`

Public methods

Method Description
fetchScoringDecision Resolves the partner override or fallback callback, sends the request with a 3 second timeout, and returns a normalized ScoringDecision or null when no callback target is available.

Callback routing rules

Condition Result
partnerKey is missing No partner override lookup is attempted.
PARTNER_SCORING_URLS is missing The service falls back to SCORING_CALLBACK_URL when available.
PARTNER_SCORING_URLS JSON fails to parse The service ignores the override map and falls back.
partnerKey has no entry in the map The service falls back when possible.
String config contains {applicantId} GET request to the expanded URL.
String config does not contain {applicantId} POST request to the string URL.
Object config omits method POST request to the templated URL.
No partner override and no fallback URL fetchScoringDecision returns null.

Response normalization rules

Input precedence Normalized output
decision Used first when present.
outcome Used when decision is missing.
result Used when both decision and outcome are missing.
score If no decision field is present, score >= 600 becomes APPROVE; otherwise DENY.
reasons Used first when present.
reason_codes Used when reasons is missing.
Default reasons ["INSUFFICIENT_SCORE"] when the final decision is DENY and no reason list is present.
approved_limit / approvedLimit Normalized to approvedLimit.

Scoring Orchestrator Container

[!NOTE] approvedLimit is normalized by fetchScoringDecision, but it is not returned in either HTTP score response. The traced code forwards it only in the decision.completed webhook payload as approved_limit.

services/scoring-orchestrator/Dockerfile

This Dockerfile packages the fallback scoring service that the API can call through SCORING_CALLBACK_URL. The image is minimal, production-only, and exposes the port expected by the callback target.

Dockerfile step Effect
FROM node:18-alpine Uses the Node 18 Alpine runtime.
WORKDIR /app Sets the working directory.
COPY package.json package-lock.json ./ Copies the package manifest before install.
RUN npm ci --omit=dev Installs production dependencies only.
COPY src ./src Copies the service source code.
ENV NODE_ENV=production Marks the container as production.
EXPOSE 8082 Exposes the scoring service port.
CMD ["node", "src/index.js"] Starts the orchestrator entrypoint.

US Scoring Routes

apps/api/src/routes/us/index.ts

The US scoring routes require partner-auth mode, read the latest evidence snapshot for the consent, and then call fetchScoringDecision with a payload that includes request_id, applicant_id, consent_id, evidence_ref, and purpose. They normalize the response differently depending on whether the client calls the submission endpoint or the score retrieval endpoint.

Execution path

  1. authPlugin requires X-Request-Id and a bearer token before the handler runs.
  2. requirePartnerAuth rejects access-token contexts by returning TOKEN_NOT_ALLOWED when request.usAccess is already populated.
  3. The handler loads the consent and checks that it is active.
  4. The handler reads the latest evidence snapshot for the consent.
  5. The handler builds the scoring payload and calls fetchScoringDecision.
  6. If a tenant exists, the route emits decision.completed with approved_limit and reasons.
  7. The handler returns the normalized response or a provider error.

API endpoints

US Partner Scoring Submission

{
    "title": "US Partner Scoring Submission",
    "description": "Submits a scoring request for an active US consent by routing to a partner override or the fallback scoring callback, then returns the normalized decision payload.",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_api_key>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<request_id>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"cons_us_123\",\n    \"evidence_ref\": \"evid_us_7f8d2c\",\n    \"decision\": \"APPROVE\",\n    \"reasons\": [\n        \"CONSISTENT_PAYMENT_HISTORY\"\n    ],\n    \"score\": 742\n}"
        },
        "400": {
            "description": "Provider returned a deny decision with an empty reason list",
            "body": "{\n    \"error\": {\n        \"code\": \"LEGAL_RESTRICTION\",\n        \"message\": \"Reason codes required\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "401": {
            "description": "Unauthorized or partner auth rejected",
            "body": "{\n    \"error\": {\n        \"code\": \"unauthorized\",\n        \"message\": \"Authorization: Bearer <PARTNER_API_KEY> is required\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "409": {
            "description": "Consent or connection state prevents scoring",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_active\",\n        \"message\": \"The consent cons_us_123 is not in ACTIVE status.\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "422": {
            "description": "Score is not ready because no scoring data was returned",
            "body": "{\n    \"error\": {\n        \"code\": \"score_not_ready\",\n        \"message\": \"Score not yet available\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "502": {
            "description": "Provider callback failed or timed out",
            "body": "{\n    \"error\": {\n        \"code\": \"provider_unavailable\",\n        \"message\": \"Scoring provider error\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": true\n    }\n}"
        }
    }
}

US Scoring Detail

{
    "title": "US Scoring Detail",
    "description": "Returns the scored summary for an active US consent after the latest evidence snapshot has been computed and the callback target has responded.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/:consentId/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_api_key>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<request_id>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_us_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"cons_us_123\",\n    \"applicant_id\": \"app_us_001\",\n    \"score\": 742,\n    \"score_range\": {\n        \"min\": 300,\n        \"max\": 850\n    },\n    \"decision\": \"APPROVE\",\n    \"score_factors\": [\n        \"CONSISTENT_PAYMENT_HISTORY\"\n    ],\n    \"evidence_ref\": \"evid_us_7f8d2c\",\n    \"scored_at\": \"2026-03-31T10:15:30.000Z\",\n    \"model_version\": \"1.2.0\"\n}"
        },
        "404": {
            "description": "Consent or evidence snapshot not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "422": {
            "description": "Evidence snapshot is missing or the score is not yet available",
            "body": "{\n    \"error\": {\n        \"code\": \"score_not_ready\",\n        \"message\": \"Feature computation has not completed. Wait for score.completed webhook.\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "502": {
            "description": "Provider callback failed or timed out",
            "body": "{\n    \"error\": {\n        \"code\": \"provider_unavailable\",\n        \"message\": \"Scoring provider error\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": true\n    }\n}"
        }
    }
}

US route behavior summary

Aspect Behavior
Auth mode Partner token only; access-token context is rejected.
Evidence dependency Requires the latest evidence snapshot.
Callback fallback Uses SCORING_CALLBACK_URL when no partner override is resolved.
Request payload to callback JSON body for POST, URL-templated GET when {applicantId} is present.
Decision propagation decision, reasons, and score are returned to the caller; approved_limit is forwarded to the webhook payload.
Deny handling A deny decision with no reasons produces LEGAL_RESTRICTION on the submission endpoint.

JP Scoring Routes

[!NOTE] The traced US POST /consents/:consentId/score handler returns HTTP 422 score_not_ready when fetchScoringDecision resolves to null, but the declared route schema does not list 422. Generated clients based only on the schema will miss that runtime status.

apps/api/src/routes/jp/index.ts

The JP routes use the same scoring service helper, the same request payload fields, and the same callback fallback rules. The main difference is how missing callback data is surfaced and how the score summary contracts the decision label.

Execution path

  1. authPlugin requires X-Request-Id and a bearer token before the handler runs.
  2. requirePartnerAuth rejects access-token contexts by returning TOKEN_NOT_ALLOWED when request.jpAccess is already populated.
  3. The handler loads the consent and checks that it is active.
  4. The handler reads the latest evidence snapshot for the consent.
  5. The handler builds the scoring payload and calls fetchScoringDecision.
  6. If a tenant exists, the route emits decision.completed with approved_limit and reasons.
  7. The handler returns the normalized response or a provider error.

API endpoints

JP Partner Scoring Submission

{
    "title": "JP Partner Scoring Submission",
    "description": "Submits a scoring request for an active JP consent by routing to a partner override or the fallback scoring callback, then returns the normalized decision payload.",
    "method": "POST",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_api_key>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<request_id>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"cons_jp_123\",\n    \"evidence_ref\": \"evid_jp_19ab44\",\n    \"decision\": \"APPROVE\",\n    \"reasons\": [\n        \"CONSISTENT_PAYMENT_HISTORY\"\n    ],\n    \"score\": 715\n}"
        },
        "400": {
            "description": "Provider returned a deny decision with an empty reason list",
            "body": "{\n    \"error\": {\n        \"code\": \"LEGAL_RESTRICTION\",\n        \"message\": \"Reason codes required\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "401": {
            "description": "Unauthorized or partner auth rejected",
            "body": "{\n    \"error\": {\n        \"code\": \"unauthorized\",\n        \"message\": \"Authorization: Bearer <PARTNER_API_KEY> is required\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "409": {
            "description": "Consent or connection state prevents scoring",
            "body": "{\n    \"error\": {\n        \"code\": \"consent_not_active\",\n        \"message\": \"The consent cons_jp_123 is not in ACTIVE status.\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "502": {
            "description": "Provider callback failed, timed out, or is unavailable",
            "body": "{\n    \"error\": {\n        \"code\": \"provider_unavailable\",\n        \"message\": \"Scoring unavailable\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": true\n    }\n}"
        }
    }
}

JP Scoring Detail

{
    "title": "JP Scoring Detail",
    "description": "Returns the scored summary for an active JP consent after the latest evidence snapshot has been computed and the callback target has responded.",
    "method": "GET",
    "baseUrl": "<LitaApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/:consentId/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <partner_api_key>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "<request_id>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "cons_jp_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"cons_jp_123\",\n    \"applicant_id\": \"app_jp_001\",\n    \"score\": 715,\n    \"score_range\": {\n        \"min\": 300,\n        \"max\": 850\n    },\n    \"decision\": \"APPROVE\",\n    \"score_factors\": [\n        \"CONSISTENT_PAYMENT_HISTORY\"\n    ],\n    \"evidence_ref\": \"evid_jp_19ab44\",\n    \"scored_at\": \"2026-03-31T10:15:30.000Z\",\n    \"model_version\": \"1.2.0\"\n}"
        },
        "404": {
            "description": "Consent or evidence snapshot not found",
            "body": "{\n    \"error\": {\n        \"code\": \"not_found\",\n        \"message\": \"Consent not found\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "422": {
            "description": "Evidence snapshot is missing or the score is not yet available",
            "body": "{\n    \"error\": {\n        \"code\": \"score_not_ready\",\n        \"message\": \"Feature computation has not completed. Wait for score.completed webhook.\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": false\n    }\n}"
        },
        "502": {
            "description": "Provider callback failed or timed out",
            "body": "{\n    \"error\": {\n        \"code\": \"provider_unavailable\",\n        \"message\": \"Scoring provider error\",\n        \"request_id\": \"req_01hzhg7z0q8j3b8\",\n        \"retryable\": true\n    }\n}"
        }
    }
}

JP route behavior summary

Aspect Behavior
Auth mode Partner token only; access-token context is rejected.
Evidence dependency Requires the latest evidence snapshot.
Callback fallback Uses SCORING_CALLBACK_URL when no partner override is resolved.
Request payload to callback JSON body for POST, URL-templated GET when {applicantId} is present.
Decision propagation decision, reasons, and score are returned to the caller; approved_limit is forwarded to the webhook payload.
Deny handling A deny decision with no reasons produces LEGAL_RESTRICTION on the submission endpoint.

Feature Flows

Partner override resolution and scoring callback

sequenceDiagram
  participant Client as Partner client
  participant Auth as Auth gate
  participant Route as US or JP score route
  participant Service as Partner scoring service
  participant Target as Callback target
  participant Webhook as Decision completed webhook

  Client->>Auth: Bearer token and X Request Id
  Auth->>Route: authenticated request
  Route->>Route: load consent and latest evidence snapshot
  Route->>Service: fetchScoringDecision

  alt partner override resolved
    Service->>Target: GET or POST partner URL
  else fallback scoring url available
    Service->>Target: POST SCORING_CALLBACK_URL
  else no callback target
    Service-->>Route: null
    Route-->>Client: score not ready or provider unavailable
  end

  Target-->>Service: raw provider payload
  Service-->>Route: normalized ScoringDecision
  Route->>Webhook: decision completed with approved_limit and reasons
  Route-->>Client: score response

Callback unavailability handling

Situation Behavior in fetchScoringDecision Route result
No partner override and no fallback URL Returns null. US POST /score: 422 score_not_ready; US GET /score: 422 score_not_ready; JP POST /score: 502 PROVIDER_UNAVAILABLE; JP GET /score: 422 score_not_ready.
Callback returns non-2xx Throws partner_scoring_failed_<status> or default_scoring_failed_<status>. The route logs scoring callback failed and returns a 502 provider error.
Callback times out after 3 seconds Abort signal fires and the request fails. The route logs and returns 502 provider unavailable.
Provider returns a deny decision with no reason array normalizeDecision can still produce reasons from reason_codes or ["INSUFFICIENT_SCORE"]; explicit empty reasons: [] is rejected by the submission handlers. The submission handlers return 400 LEGAL_RESTRICTION.

Decision and reason propagation

Source field Normalized field Where it is used
decision / outcome / result decision Returned by fetchScoringDecision and consumed by both region routes.
reasons / reason_codes reasons Returned in the submission response and forwarded to decision.completed.
approved_limit / approvedLimit approvedLimit Forwarded only in decision.completed as approved_limit.
score score Returned to the caller, and included in the score summary responses.

State Management

Scoring request lifecycle

State Meaning
Consent not active The consent exists but is not in ACTIVE status, so scoring is rejected before any callback attempt.
Evidence not ready No latest evidence snapshot exists for the consent. The score endpoint returns score_not_ready before calling the provider.
Callback resolved A partner override or fallback URL has been selected.
Callback in flight fetchScoringDecision is waiting on the provider response within the 3 second timeout.
Decision normalized The provider payload has been converted to the shared ScoringDecision shape.
Decision completed webhook emitted The route has forwarded decision, reasons, and approved_limit to downstream consumers when a tenant exists.
Provider unavailable The callback failed, timed out, or was not configured, and the route returned a 5xx or score_not_ready response depending on the handler.

Environment Variables

Variable Read by Purpose
PARTNER_SCORING_URLS apps/api/src/services/partner-scoring.ts JSON map of partnerKey to either a URL string or an object config with url and optional method.
SCORING_CALLBACK_URL apps/api/src/routes/us/index.ts, apps/api/src/routes/jp/index.ts Fallback callback URL used when no partner override is resolved.
API_PUBLIC_BASE_URL apps/api/src/routes/us/index.ts, apps/api/src/routes/jp/index.ts Used by consent creation to build region authorization URLs; it is not part of the scoring request path but sits in the same public API surface.

Example configuration shape

{
  "partner_key_1": "https://partner.example/scoring/{applicantId}",
  "partner_key_2": {
    "url": "https://partner.example/scoring",
    "method": "POST"
  }
}

Dependencies

Dependency Role in scoring flow
fetch Sends the outbound callback request to the partner override or fallback provider.
AbortController Enforces the 3 second callback timeout.
randomUUID Produces the request_id value sent in the scoring payload.
fastify Hosts the US and JP route handlers and their auth gating.
zod Defines the route schemas for params and responses.
@lita/webhooks Receives the decision.completed payload that carries approved_limit and reasons.
node:18-alpine runtime Packages the scoring-orchestrator container from services/scoring-orchestrator/Dockerfile.

Testing Considerations

Scenario What to verify
Partner override string contains {applicantId} The service uses GET and inserts the URL-encoded applicant ID.
Partner override object omits method The service defaults to POST.
Invalid PARTNER_SCORING_URLS JSON The service falls back to SCORING_CALLBACK_URL or returns null when no fallback exists.
Provider returns only score normalizeDecision derives APPROVE for scores >= 600 and DENY otherwise.
Provider returns DENY with empty reasons The submission endpoint returns 400 LEGAL_RESTRICTION.
No evidence snapshot exists The score endpoint returns score_not_ready before any callback call.
Callback exceeds 3 seconds The route returns a provider unavailable error and logs the failure.
Approved limit present in provider payload The value appears in the decision.completed webhook payload as approved_limit.

Key Classes Reference

[!NOTE] The JP scoring handlers preserve the same normalization pattern as the US surface, but the GET /consents/:consentId/score response remaps DENY to DECLINE, MANUAL_REVIEW to REVIEW, and keeps any other provider decision string as-is. [!NOTE] The US POST /consents/:consentId/score handler has a runtime 422 score_not_ready branch, but its route schema omits 422. That mismatch is specific to the US submission endpoint and does not appear in the GET score contract.

Class Responsibility
partner-scoring.ts Resolves partner-scoring callback URLs, sends scoring requests, and normalizes provider responses.
index.ts Defines the US scoring routes and their partner-auth, evidence, and callback flow.
index.ts Defines the JP scoring routes and their partner-auth, evidence, and callback flow.
Dockerfile Builds the scoring-orchestrator container used by the fallback callback URL.