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` |
| 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
authPlugin requires X-Request-Id and a bearer token before the handler runs.
requirePartnerAuth rejects access-token contexts by returning TOKEN_NOT_ALLOWED when request.usAccess is already populated.
- The handler loads the consent and checks that it is active.
- The handler reads the latest evidence snapshot for the consent.
- The handler builds the scoring payload and calls
fetchScoringDecision.
- If a tenant exists, the route emits
decision.completed with approved_limit and reasons.
- 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
authPlugin requires X-Request-Id and a bearer token before the handler runs.
requirePartnerAuth rejects access-token contexts by returning TOKEN_NOT_ALLOWED when request.jpAccess is already populated.
- The handler loads the consent and checks that it is active.
- The handler reads the latest evidence snapshot for the consent.
- The handler builds the scoring payload and calls
fetchScoringDecision.
- If a tenant exists, the route emits
decision.completed with approved_limit and reasons.
- 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. |