Regional Data Gateways Domain - US and JP Route Modules, Parity, and Region Specific Request Paths
Overview
The US and JP route modules expose the regional data-gateway surface for consent creation, authorization, token exchange, consent-scoped data access, feature computation, scoring replay, token lifecycle operations, and revocation. The same lifecycle is implemented twice, once under /api/v1/us and once under /api/v1/jp, so the API can keep region-specific pathing and data residency while preserving parity in consent, access, and replay flows.
The repository smoke surface validates that parity end-to-end. scripts/check-all-api-paths.sh drives the US and JP sequences with live HTTP calls, captures consent and token artifacts, and checks that both regions support the same operational stages: consent issuance, authorization, data access, feature computation, scoring, refresh, introspection, and revoke.
Architecture Overview
flowchart TD
subgraph APIService [API Service]
Server[API Server]
USRoutes[usRoutes]
JPRoutes[jpRoutes]
USGuards[US route guards]
JPGuards[JP route guards]
USService[us-api service facade]
JPService[jp-api service facade]
Scoring[partner-scoring]
Webhooks[Webhook delivery service]
end
subgraph SmokeChecks [Regional smoke checks]
CheckAll[scripts check-all-api-paths.sh]
end
Server --> USRoutes
Server --> JPRoutes
USRoutes --> USGuards
JPRoutes --> JPGuards
USRoutes --> USService
JPRoutes --> JPService
USRoutes --> Scoring
JPRoutes --> Scoring
USRoutes --> Webhooks
JPRoutes --> Webhooks
CheckAll --> Server
Regional Path Parity
[!IMPORTANT]
The US smoke path in scripts/check-all-api-paths.sh posts GENERAL_PERSONAL_FINANCE to POST /api/v1/us/consents, but purposeSchema in apps/api/src/routes/us/index.ts only accepts the seven US purposes listed in that schema. That request would be rejected by schema validation before the handler runs.
The two route modules implement the same lifecycle with region-specific prefixes and regionalized data handling.
| Lifecycle Stage |
US Path |
JP Path |
Region Specific Behavior |
| Create consent |
POST /api/v1/us/consents |
POST /api/v1/jp/consents |
JP accepts appi_provision; both accept refresh permissions |
| Consent detail |
GET /api/v1/us/consents/:consentId |
GET /api/v1/jp/consents/:consentId |
Partner-auth only |
| Authorize |
GET /api/v1/us/consents/:consentId/authorize |
GET /api/v1/jp/consents/:consentId/authorize |
No auth guard on either path |
| Receipt |
GET /api/v1/us/consents/:consentId/receipt |
GET /api/v1/jp/consents/:consentId/receipt |
JP includes appi_provision in the receipt |
| Token exchange |
POST /api/v1/us/consents/:consentId/token |
POST /api/v1/jp/consents/:consentId/token |
Partner-auth only |
| Token refresh |
POST /api/v1/us/tokens/refresh |
POST /api/v1/jp/tokens/refresh |
Partner-auth only |
| Token introspection |
POST /api/v1/us/tokens/introspect |
POST /api/v1/jp/tokens/introspect |
Partner-auth only |
| Accounts |
GET /api/v1/us/data/accounts and GET /api/v1/us/consents/:consentId/data/accounts |
GET /api/v1/jp/data/accounts and GET /api/v1/jp/consents/:consentId/data/accounts |
Access-token gated; consent-scoped variants check path token consistency |
| Balances |
GET /api/v1/us/data/balances and GET /api/v1/us/consents/:consentId/data/balances |
GET /api/v1/jp/data/balances and GET /api/v1/jp/consents/:consentId/data/balances |
Same model across regions |
| Transactions |
GET /api/v1/us/data/transactions, GET /api/v1/us/data/transactions/sync, GET /api/v1/us/consents/:consentId/data/transactions |
GET /api/v1/jp/data/transactions, GET /api/v1/jp/data/transactions/sync, GET /api/v1/jp/consents/:consentId/data/transactions |
JP and US use the same transaction shape; consent-scoped variants paginate |
| Income |
GET /api/v1/us/data/income and GET /api/v1/us/consents/:consentId/data/income |
GET /api/v1/jp/data/income and GET /api/v1/jp/consents/:consentId/data/income |
Same output shape |
| Feature compute |
POST /api/v1/us/features/compute and POST /api/v1/us/consents/:consentId/features/compute |
POST /api/v1/jp/features/compute and POST /api/v1/jp/consents/:consentId/features/compute |
Dual mode in both regions: partner-auth job mode or access-token direct mode |
| Score |
GET /api/v1/us/consents/:consentId/score |
GET /api/v1/jp/consents/:consentId/score |
Both replay from stored evidence and call the scoring service |
| Evidence replay |
GET /api/v1/us/evidence/:evidenceRef |
GET /api/v1/jp/evidence/:evidenceRef |
Partner-auth only |
| KYC |
GET /api/v1/us/consents/:consentId/kyc |
GET /api/v1/jp/consents/:consentId/kyc |
Partner-auth only |
| Job status |
GET /api/v1/us/status/:jobId |
GET /api/v1/jp/status/:jobId |
Partner-auth only |
| Revoke |
POST /api/v1/us/consents/:consentId/revoke |
POST /api/v1/jp/consents/:consentId/revoke and DELETE /api/v1/jp/consents/:consentId |
JP exposes both revoke paths |
Shared Data Shapes
Error Response
errorResponseSchema is the common error envelope used by both route modules.
| Property |
Type |
Description |
error.code |
string |
Stable machine code |
error.message |
string |
Human-readable message |
error.request_id |
string |
Request correlation identifier |
error.retryable |
boolean |
Retry hint returned by the handler |
Consent Summary
Used by GET /consents/:consentId, GET /consents/:consentId/authorize, and GET /consents/:consentId/receipt.
| Property |
Type |
Description |
consent_id |
string |
Consent identifier |
status |
string |
Current consent status |
applicant_id |
`string \ |
null` |
purpose |
string |
Consent purpose |
redirect_url |
string |
Authorization redirect target |
created_at |
string |
Creation timestamp |
activated_at |
`string \ |
null` |
expires_at |
string |
Expiration timestamp |
revoked_at |
`string \ |
null` |
connections |
Array |
Connection list for the consent |
disclosure_version |
string |
Receipt version |
appi_provision |
`Record<string, unknown> \ |
null` |
Connection Entry
| Property |
Type |
Description |
connection_id |
string |
Connection identifier |
provider |
string |
Display provider name |
status |
string |
Connection status |
Account Entry
| Property |
Type |
Description |
account_id |
string |
Account identifier |
name |
string |
Account display name |
type |
string |
Account type |
mask |
string |
Masked identifier |
institution |
string |
Financial institution |
Balance Entry
| Property |
Type |
Description |
account_id |
string |
Account identifier |
available |
number |
Available balance |
current |
number |
Current balance |
currency |
string |
Currency code |
Transaction Entry
| Property |
Type |
Description |
transaction_id |
string |
Transaction identifier |
account_id |
string |
Account identifier |
posted_at |
string |
Posting timestamp |
date |
string |
Date-only view used by paginated list endpoints |
amount |
number |
Transaction amount |
currency |
string |
Currency code |
description |
string |
Transaction description |
category |
string |
Transaction category |
type |
string |
CREDIT or DEBIT |
Income Summary
| Property |
Type |
Description |
method |
string |
Calculation method |
gross_monthly |
number |
Gross monthly income |
net_monthly |
number |
Net monthly income |
currency |
string |
Currency code |
Sync Response
| Property |
Type |
Description |
cursor |
string |
Sync cursor |
added |
Array |
New transactions |
modified |
Array |
Updated transactions |
removed |
Array |
Removed transaction identifiers |
Feature Compute Response
| Property |
Type |
Description |
evidence_ref |
string |
Stored evidence snapshot reference |
features |
Record<string, number> |
Computed feature values |
Job Record
| Property |
Type |
Description |
jobId |
string |
In-memory job identifier |
status |
`PROCESSING \ |
COMPLETE \ |
consentId |
string |
Consent linked to the job |
completedAt |
`string \ |
undefined` |
error |
`string \ |
undefined` |
Score Response
| Property |
Type |
Description |
consent_id |
string |
Consent identifier |
applicant_id |
`string \ |
null` |
score |
`number \ |
null` |
score_range |
object |
Min and max score range |
decision |
string |
Decision string |
score_factors |
Array<string> |
Decision factors |
evidence_ref |
`string \ |
null` |
scored_at |
`string \ |
null` |
model_version |
string |
Model version |
KYC Response
| Property |
Type |
Description |
consent_id |
string |
Consent identifier |
status |
string |
KYC state |
checks.identity.status |
string |
Identity check status |
checks.identity.method |
string |
Identity method |
checks.sanctions.status |
string |
Sanctions check status |
checks.sanctions.lists_screened |
Array<string> |
Screened lists |
checks.pep.status |
string |
PEP check status |
checks.aml.status |
string |
AML check status |
checks.aml.risk_level |
string |
AML risk level |
completed_at |
`string \ |
null` |
Evidence Replay Response
| Property |
Type |
Description |
evidence_ref |
string |
Evidence reference |
consent_id |
string |
Consent identifier |
applicant_id |
`string \ |
null` |
snapshot_version |
string |
Evidence schema version |
created_at |
string |
Snapshot timestamp |
score_inputs |
object |
Replay inputs |
kyc_result |
object |
KYC result used for replay |
delinquency_bucket |
string |
Derived delinquency bucket |
features |
Record<string, number> |
Stored feature map |
US Regional Data Gateway
apps/api/src/routes/us/index.ts
The US route module implements the regional API surface for US tenants. It uses partner-auth routes for consent management, token exchange, revocation, KYC, scoring, and replay, and access-token routes for consent-scoped and direct data access. The route handlers use the US service facade for storage and state transitions and the partner scoring service for score and replay operations.
Public Methods
| Method |
Description |
usRoutes |
Registers the US regional routes under the Fastify plugin |
Route Guards and Helpers
| Method |
Description |
requireAccessToken |
Rejects requests that do not have a resolved US access context |
requirePartnerAuth |
Rejects requests that already have a US access context and therefore are not partner-auth only |
ensurePurpose |
Compares the optional x-purpose header with the access-context purpose |
ensureCategory |
Checks that the requested data category is permitted by the access context |
ensureConnection |
Loads the consent connection, degrades stale active connections, and rejects revoked or disconnected states |
emitWebhook |
Fan-outs webhook events to every registered endpoint for the tenant |
usJobStore |
Holds job results for partner-auth feature compute requests |
Regional Request Flow
| Stage |
US Behavior |
| Consent creation |
Partner-auth only, returns authorization redirect URLs |
| Data access |
Access-token only, with purpose and category checks |
| Feature compute |
Partner-auth job mode when consent_id is in the body, access-token direct mode otherwise |
| Score replay |
Reads stored evidence, calls fetchScoringDecision, emits decision.completed |
| Refresh/introspect |
Partner-auth only |
| Revoke |
Partner-auth only |
Create Consent
{
"title": "Create US Consent",
"description": "Creates a US consent, returns the authorization redirect URL, and initializes the consent lifecycle",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"applicant_id\": \"app_us_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"data_categories\": [\n \"ACCOUNTS\",\n \"BALANCES\",\n \"TRANSACTIONS\",\n \"INCOME\",\n \"CASHFLOW_FEATURES\"\n ],\n \"expires_in_days\": 30,\n \"refresh_permissions\": {\n \"enabled\": true,\n \"max_refresh_per_day\": 8\n },\n \"user\": {\n \"country\": \"US\"\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Consent created",
"body": "{\n \"consent_id\": \"cons_us_1001\",\n \"authorization_url\": \"https://api.joinlita.com/api/v1/us/consents/cons_us_1001/authorize\",\n \"redirect_url\": \"https://api.joinlita.com/api/v1/us/consents/cons_us_1001/authorize\",\n \"status\": \"PENDING\",\n \"expires_at\": \"2026-02-01T12:00:00.000Z\"\n}"
},
"401": {
"description": "Partner auth required",
"body": "{\n \"error\": {\n \"code\": \"TOKEN_NOT_ALLOWED\",\n \"message\": \"Partner token required\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get Consent
{
"title": "Get US Consent",
"description": "Returns the current consent state and active connection list",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent record",
"body": "{\n \"consent_id\": \"cons_us_1001\",\n \"status\": \"ACTIVE\",\n \"applicant_id\": \"app_us_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"activated_at\": \"2026-01-02T00:00:00.000Z\",\n \"expires_at\": \"2026-02-01T12:00:00.000Z\",\n \"connections\": [\n {\n \"connection_id\": \"conn_us_1001\",\n \"provider\": \"Financial Provider\",\n \"status\": \"ACTIVE\"\n }\n ]\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Authorize US Consent
{
"title": "Authorize US Consent",
"description": "Returns the authorization code view used to exchange the consent for tokens",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/authorize",
"headers": [],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Authorization complete",
"body": "{\n \"consent_id\": \"cons_us_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"data_categories\": [\n \"accounts\",\n \"balances\",\n \"transactions\",\n \"income\",\n \"cashflow_features\"\n ],\n \"status\": \"ACTIVE\",\n \"authorization_code\": \"ok\",\n \"message\": \"Authorization complete. Exchange this code for an access token via POST /consents/:consentId/token\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"consent_not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
},
"409": {
"description": "Consent expired or revoked",
"body": "{\n \"error\": {\n \"code\": \"consent_revoked\",\n \"message\": \"Consent has expired\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Consent Receipt
{
"title": "Get US Consent Receipt",
"description": "Returns the consent receipt for partner audit workflows",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/receipt",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Receipt document",
"body": "{\n \"consent_id\": \"cons_us_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"data_categories\": [\n \"accounts\",\n \"balances\",\n \"transactions\",\n \"income\",\n \"cashflow_features\"\n ],\n \"disclosure_version\": \"1.0.0\",\n \"status\": \"ACTIVE\",\n \"created_at\": \"2026-01-01T12:00:00.000Z\",\n \"revoked_at\": null\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_NOT_FOUND\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Revoke US Consent
{
"title": "Revoke US Consent",
"description": "Revokes a consent and returns the revoked state",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/revoke",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent revoked",
"body": "{\n \"consent_id\": \"cons_us_1001\",\n \"status\": \"REVOKED\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_NOT_FOUND\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Exchange US Consent Token
{
"title": "Exchange US Consent Token",
"description": "Exchanges the authorization code for access and refresh tokens",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/token",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "json",
"requestBody": "{\n \"authorization_code\": \"ok\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Token exchange result",
"body": "{\n \"access_token\": \"acc_us_1001\",\n \"refresh_token\": \"ref_us_1001\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\",\n \"scope\": \"data:read data:write\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_NOT_FOUND\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Refresh US Access Token
{
"title": "Refresh US Access Token",
"description": "Refreshes an access token and can trigger a reauth webhook when the refresh limit is exceeded",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/tokens/refresh",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"refresh_token\": \"ref_us_1001\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Refreshed token pair",
"body": "{\n \"access_token\": \"acc_us_2001\",\n \"refresh_token\": \"ref_us_2001\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\",\n \"scope\": \"data:read data:write\"\n}"
},
"400": {
"description": "Refresh not allowed",
"body": "{\n \"error\": {\n \"code\": \"REFRESH_LIMIT_EXCEEDED\",\n \"message\": \"Refresh not allowed\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
},
"401": {
"description": "Partner auth required",
"body": "{\n \"error\": {\n \"code\": \"TOKEN_NOT_ALLOWED\",\n \"message\": \"Partner token required\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Introspect US Token
{
"title": "Introspect US Token",
"description": "Returns token activity and the consent scope attached to the token",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/tokens/introspect",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"token\": \"acc_us_1001\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Token introspection result",
"body": "{\n \"active\": true,\n \"expires_at\": \"2026-01-01T13:00:00.000Z\",\n \"consent_id\": \"cons_us_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"data_categories\": [\n \"accounts\",\n \"balances\",\n \"transactions\",\n \"income\",\n \"cashflow_features\"\n ]\n}"
}
}
}
Get US Accounts
{
"title": "Get US Accounts",
"description": "Returns account records for the access-token consent context",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/data/accounts",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Account list",
"body": "{\n \"accounts\": [\n {\n \"account_id\": \"acct_us_1001\",\n \"name\": \"Primary Checking\",\n \"type\": \"checking\",\n \"mask\": \"1234\",\n \"institution\": \"Financial Provider\"\n }\n ]\n}"
},
"401": {
"description": "Access token required",
"body": "{\n \"error\": {\n \"code\": \"ACCESS_TOKEN_REQUIRED\",\n \"message\": \"Access token required\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
},
"403": {
"description": "Category or purpose denied",
"body": "{\n \"error\": {\n \"code\": \"CATEGORY_NOT_ALLOWED\",\n \"message\": \"accounts not permitted by consent\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Consent Accounts
{
"title": "Get US Consent Accounts",
"description": "Returns accounts for a consent-scoped path and rejects consent-token mismatches",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/data/accounts",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Account list",
"body": "{\n \"accounts\": [\n {\n \"account_id\": \"acct_us_1001\",\n \"name\": \"Primary Checking\",\n \"type\": \"checking\",\n \"mask\": \"1234\",\n \"institution\": \"Financial Provider\"\n }\n ]\n}"
},
"403": {
"description": "Consent mismatch or category denied",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_MISMATCH\",\n \"message\": \"Consent ID does not match token\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Balances
{
"title": "Get US Balances",
"description": "Returns available and current balances for the access-token consent context",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/data/balances",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Balance list",
"body": "{\n \"balances\": [\n {\n \"account_id\": \"acct_us_1001\",\n \"available\": 1250.5,\n \"current\": 1400.75,\n \"currency\": \"USD\"\n }\n ]\n}"
},
"401": {
"description": "Access token required",
"body": "{\n \"error\": {\n \"code\": \"ACCESS_TOKEN_REQUIRED\",\n \"message\": \"Access token required\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Consent Balances
{
"title": "Get US Consent Balances",
"description": "Returns balances for a consent-scoped path and rejects consent-token mismatches",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/data/balances",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Balance list",
"body": "{\n \"balances\": [\n {\n \"account_id\": \"acct_us_1001\",\n \"available\": 1250.5,\n \"current\": 1400.75,\n \"currency\": \"USD\"\n }\n ]\n}"
},
"403": {
"description": "Consent mismatch",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_MISMATCH\",\n \"message\": \"Consent ID does not match token\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Transactions
{
"title": "Get US Transactions",
"description": "Returns transactions filtered by date for the access-token consent context",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/data/transactions",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [
{
"key": "start_date",
"value": "2026-01-01",
"required": false
},
{
"key": "end_date",
"value": "2026-12-31",
"required": false
}
],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Transaction list",
"body": "{\n \"transactions\": [\n {\n \"transaction_id\": \"txn_us_1001\",\n \"account_id\": \"acct_us_1001\",\n \"posted_at\": \"2026-01-15T09:12:00Z\",\n \"amount\": -42.5,\n \"currency\": \"USD\",\n \"description\": \"Coffee Shop\",\n \"category\": \"food_and_drink\",\n \"type\": \"DEBIT\"\n }\n ]\n}"
},
"401": {
"description": "Access token required",
"body": "{\n \"error\": {\n \"code\": \"ACCESS_TOKEN_REQUIRED\",\n \"message\": \"Access token required\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Transaction Sync
{
"title": "Get US Transaction Sync",
"description": "Returns a sync payload for transaction deltas",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/data/transactions/sync",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [
{
"key": "cursor",
"value": "demo",
"required": false
},
{
"key": "limit",
"value": "50",
"required": false
}
],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Transaction delta page",
"body": "{\n \"cursor\": \"cur_50\",\n \"added\": [\n {\n \"transaction_id\": \"txn_us_1001\",\n \"account_id\": \"acct_us_1001\",\n \"posted_at\": \"2026-01-15T09:12:00Z\",\n \"amount\": -42.5,\n \"currency\": \"USD\",\n \"description\": \"Coffee Shop\",\n \"category\": \"food_and_drink\"\n }\n ],\n \"modified\": [\n {\n \"transaction_id\": \"txn_us_1002\",\n \"account_id\": \"acct_us_1001\",\n \"posted_at\": \"2026-01-16T09:12:00Z\",\n \"amount\": 1200,\n \"currency\": \"USD\",\n \"description\": \"Payroll\",\n \"category\": \"income\"\n }\n ],\n \"removed\": [\n {\n \"transaction_id\": \"txn_us_1003\"\n }\n ]\n}"
},
"401": {
"description": "Access token required",
"body": "{\n \"error\": {\n \"code\": \"ACCESS_TOKEN_REQUIRED\",\n \"message\": \"Access token required\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Consent Transactions
{
"title": "Get US Consent Transactions",
"description": "Returns paginated transactions for a consent-scoped path",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/data/transactions",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [
{
"key": "from_date",
"value": "2026-01-01",
"required": false
},
{
"key": "to_date",
"value": "2026-01-31",
"required": false
},
{
"key": "limit",
"value": "25",
"required": false
},
{
"key": "cursor",
"value": "cur_0",
"required": false
}
],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Paginated transaction response",
"body": "{\n \"data\": [\n {\n \"transaction_id\": \"txn_us_1001\",\n \"date\": \"2026-01-15\",\n \"amount\": -42.5,\n \"currency\": \"USD\",\n \"description\": \"Coffee Shop\",\n \"category\": \"food_and_drink\",\n \"type\": \"DEBIT\"\n }\n ],\n \"next_cursor\": \"cur_25\",\n \"total_count\": 1\n}"
},
"403": {
"description": "Consent mismatch or category denied",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_MISMATCH\",\n \"message\": \"Consent ID does not match token\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Income
{
"title": "Get US Income",
"description": "Returns monthly income totals for the access-token consent context",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/data/income",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Income summary",
"body": "{\n \"method\": \"DIRECT\",\n \"gross_monthly\": 6500,\n \"net_monthly\": 5200,\n \"currency\": \"USD\"\n}"
}
}
}
Get US Consent Income
{
"title": "Get US Consent Income",
"description": "Returns monthly income totals for a consent-scoped path",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/data/income",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Income summary",
"body": "{\n \"method\": \"DIRECT\",\n \"gross_monthly\": 6500,\n \"net_monthly\": 5200,\n \"currency\": \"USD\"\n}"
}
}
}
Compute US Features
{
"title": "Compute US Features",
"description": "Computes cashflow features. When consent_id is present, the route runs in partner-auth job mode and returns 202; otherwise it runs in access-token direct mode and returns 200",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/features/compute",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token_or_access_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_id\": \"cons_us_1001\",\n \"feature_set\": \"US_CASHFLOW_V1\",\n \"as_of\": \"2026-01-15T00:00:00Z\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"202": {
"description": "Partner-auth job accepted",
"body": "{\n \"job_id\": \"job_a1b2c3d4e5f6\",\n \"status\": \"PROCESSING\",\n \"consent_id\": \"cons_us_1001\",\n \"estimated_completion_ms\": 0\n}"
},
"200": {
"description": "Direct compute result",
"body": "{\n \"evidence_ref\": \"evidence_us_1001\",\n \"features\": {\n \"monthly_income\": 5200,\n \"avg_balance\": 1400.75,\n \"overdraft_count\": 1,\n \"cashflow_surplus\": 1450.25,\n \"cashflow_inflow\": 4800,\n \"cashflow_outflow\": 3349.75,\n \"cashflow_net\": 1450.25\n }\n}"
}
}
}
Get US Score
{
"title": "Get US Score",
"description": "Replays the stored evidence through the scoring provider and returns the derived decision",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/score",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Score replay result",
"body": "{\n \"consent_id\": \"cons_us_1001\",\n \"applicant_id\": \"app_us_1001\",\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\": \"evidence_us_1001\",\n \"scored_at\": \"2026-01-15T12:00:00.000Z\",\n \"model_version\": \"1.2.0\"\n}"
},
"422": {
"description": "Consent not active or score not ready",
"body": "{\n \"error\": {\n \"code\": \"score_not_ready\",\n \"message\": \"Feature computation has not completed. Wait for score.completed webhook.\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
},
"502": {
"description": "Scoring provider unavailable",
"body": "{\n \"error\": {\n \"code\": \"provider_unavailable\",\n \"message\": \"Scoring provider error\",\n \"request_id\": \"req_123\",\n \"retryable\": true\n }\n}"
}
}
}
Get US Evidence Replay
{
"title": "Get US Evidence Replay",
"description": "Rebuilds a score input view from a stored evidence snapshot",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/evidence/:evidenceRef",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "evidenceRef",
"value": "evidence_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Evidence replay result",
"body": "{\n \"evidence_ref\": \"evidence_us_1001\",\n \"consent_id\": \"cons_us_1001\",\n \"applicant_id\": \"app_us_1001\",\n \"snapshot_version\": \"1.2.0\",\n \"created_at\": \"2026-01-15T12:00:00.000Z\",\n \"score_inputs\": {\n \"payment_behavior\": {\n \"payments_observed\": 48,\n \"avg_payment_delay_days\": 2,\n \"late_payment_count_30d_plus\": 0\n },\n \"income\": {\n \"monthly_net_income\": 5200,\n \"income_stability_score\": 0.95\n },\n \"obligations\": {\n \"total_monthly_obligations\": 1560,\n \"obligation_to_income_ratio\": 0.3\n }\n },\n \"kyc_result\": {\n \"status\": \"PASSED\",\n \"checks\": [\n \"identity\",\n \"sanctions\",\n \"pep\"\n ]\n },\n \"delinquency_bucket\": \"CURRENT\",\n \"features\": {\n \"monthly_income\": 5200,\n \"avg_balance\": 1400.75,\n \"overdraft_count\": 1,\n \"cashflow_surplus\": 1450.25,\n \"cashflow_inflow\": 4800,\n \"cashflow_outflow\": 3349.75,\n \"cashflow_net\": 1450.25\n }\n}"
},
"404": {
"description": "Evidence not found",
"body": "{\n \"error\": {\n \"code\": \"EVIDENCE_NOT_FOUND\",\n \"message\": \"Evidence not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US KYC
{
"title": "Get US KYC",
"description": "Returns the derived KYC and AML check status for a consent",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/consents/:consentId/kyc",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_us_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "KYC result",
"body": "{\n \"consent_id\": \"cons_us_1001\",\n \"status\": \"PASSED\",\n \"checks\": {\n \"identity\": {\n \"status\": \"PASSED\",\n \"method\": \"document_biometric\"\n },\n \"sanctions\": {\n \"status\": \"PASSED\",\n \"lists_screened\": [\n \"OFAC\",\n \"UN\",\n \"EU\"\n ]\n },\n \"pep\": {\n \"status\": \"PASSED\"\n },\n \"aml\": {\n \"status\": \"PASSED\",\n \"risk_level\": \"LOW\"\n }\n },\n \"completed_at\": \"2026-01-15T12:00:00.000Z\"\n}"
},
"422": {
"description": "Consent not active",
"body": "{\n \"error\": {\n \"code\": \"consent_not_active\",\n \"message\": \"KYC checks are run during feature computation. Activate the consent first.\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get US Job Status
{
"title": "Get US Job Status",
"description": "Returns the in-memory job state for partner-auth feature compute requests",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/status/:jobId",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "jobId",
"value": "job_a1b2c3d4e5f6",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Job record",
"body": "{\n \"job_id\": \"job_a1b2c3d4e5f6\",\n \"status\": \"COMPLETE\",\n \"consent_id\": \"cons_us_1001\",\n \"completed_at\": \"2026-01-15T12:00:00.000Z\",\n \"error\": null\n}"
},
"404": {
"description": "Job not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Job not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Replay US Decision
{
"title": "Replay US Decision",
"description": "Replays a stored evidence snapshot through the scoring service and returns the decision and reasons",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/us/decisions/replay",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"evidence_ref\": \"evidence_us_1001\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Replay result",
"body": "{\n \"evidence_ref\": \"evidence_us_1001\",\n \"decision\": \"APPROVE\",\n \"reasons\": [\n \"CONSISTENT_PAYMENT_HISTORY\"\n ]\n}"
},
"404": {
"description": "Evidence or consent not found",
"body": "{\n \"error\": {\n \"code\": \"EVIDENCE_NOT_FOUND\",\n \"message\": \"Evidence not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
JP Regional Data Gateway
apps/api/src/routes/jp/index.ts
The JP route module mirrors the US lifecycle while adding JP-specific request handling, including APPI disclosure payloads, JP purpose normalization, refresh_permissions, JP feature job state, and KYC-aware score responses. It uses the JP service facade for consent and evidence persistence and emits the same webhook lifecycle events as the US module, with JP-specific pathing under /api/v1/jp.
Public Methods
| Method |
Description |
jpRoutes |
Registers the JP regional routes under the Fastify plugin |
Route Guards and Helpers
| Method |
Description |
requireAccessToken |
Rejects requests that do not have a resolved JP access context |
requirePartnerAuth |
Rejects requests that already have a JP access context and therefore are not partner-auth only |
ensurePurpose |
Compares the optional x-purpose header with the access-context purpose |
ensureCategory |
Checks that the requested data category is permitted by the access context |
normalizePurpose |
Maps GENERAL_PERSONAL_FINANCE to PERSONAL_FINANCE |
normalizeDataCategory |
Maps uppercase aliases and JP-specific categories to canonical JP categories |
emitWebhook |
Fan-outs webhook events to every registered endpoint for the tenant |
ensureConnection |
Loads the consent connection, degrades stale active connections, and rejects revoked or disconnected states |
jpJobStore |
Holds job results for partner-auth feature compute requests |
JP Specific Behavior
| Stage |
JP Behavior |
| Consent creation |
Accepts appi_provision and refresh_permissions |
| Purpose normalization |
Converts GENERAL_PERSONAL_FINANCE into PERSONAL_FINANCE |
| Category normalization |
Treats payment_behavior and obligations as cashflow_features |
| Receipt |
Returns appi_provision when present |
| Feature compute |
Emits both features.computed and score.completed in partner-auth job mode |
| Decision replay |
Uses the same evidence replay shape as the US module |
| Revoke |
Supports both POST /revoke and DELETE /consents/:consentId |
Create Consent
{
"title": "Create JP Consent",
"description": "Creates a JP consent, returns the authorization redirect URL, and accepts APPI disclosure data",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"applicant_id\": \"app_jp_1001\",\n \"purpose\": \"GENERAL_PERSONAL_FINANCE\",\n \"data_categories\": [\n \"ACCOUNTS\",\n \"BALANCES\",\n \"TRANSACTIONS\",\n \"INCOME\",\n \"CASHFLOW_FEATURES\"\n ],\n \"expires_in_days\": 30,\n \"refresh_permissions\": {\n \"enabled\": true,\n \"max_refresh_per_day\": 8\n },\n \"user\": {\n \"country\": \"JP\"\n },\n \"appi_provision\": {\n \"disclosure_language\": \"ja-JP\",\n \"version\": \"2026-01\"\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Consent created",
"body": "{\n \"consent_id\": \"cons_jp_1001\",\n \"authorization_url\": \"https://api.joinlita.com/api/v1/jp/consents/cons_jp_1001/authorize\",\n \"redirect_url\": \"https://api.joinlita.com/api/v1/jp/consents/cons_jp_1001/authorize\",\n \"status\": \"PENDING\",\n \"expires_at\": \"2026-02-01T12:00:00.000Z\"\n}"
},
"401": {
"description": "Partner auth required",
"body": "{\n \"error\": {\n \"code\": \"TOKEN_NOT_ALLOWED\",\n \"message\": \"Partner token required\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get JP Consent
{
"title": "Get JP Consent",
"description": "Returns the current consent state and active connection list for JP",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent record",
"body": "{\n \"consent_id\": \"cons_jp_1001\",\n \"status\": \"ACTIVE\",\n \"applicant_id\": \"app_jp_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"activated_at\": \"2026-01-02T00:00:00.000Z\",\n \"expires_at\": \"2026-02-01T12:00:00.000Z\",\n \"connections\": [\n {\n \"connection_id\": \"conn_jp_1001\",\n \"provider\": \"Financial Provider\",\n \"status\": \"ACTIVE\"\n }\n ]\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Authorize JP Consent
{
"title": "Authorize JP Consent",
"description": "Returns the authorization code view used to exchange the consent for tokens",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/authorize",
"headers": [],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Authorization complete",
"body": "{\n \"consent_id\": \"cons_jp_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"data_categories\": [\n \"accounts\",\n \"balances\",\n \"transactions\",\n \"income\",\n \"cashflow_features\"\n ],\n \"status\": \"ACTIVE\",\n \"authorization_code\": \"ok\",\n \"message\": \"Authorization complete. Exchange this code for an access token via POST /consents/:consentId/token\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"consent_not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
},
"409": {
"description": "Consent expired or revoked",
"body": "{\n \"error\": {\n \"code\": \"consent_revoked\",\n \"message\": \"Consent has expired\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get JP Consent Receipt
{
"title": "Get JP Consent Receipt",
"description": "Returns the JP consent receipt including APPI provision data",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/receipt",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Receipt document",
"body": "{\n \"consent_id\": \"cons_jp_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"data_categories\": [\n \"accounts\",\n \"balances\",\n \"transactions\",\n \"income\",\n \"cashflow_features\"\n ],\n \"disclosure_version\": \"1.0.0\",\n \"status\": \"ACTIVE\",\n \"created_at\": \"2026-01-01T12:00:00.000Z\",\n \"revoked_at\": null,\n \"appi_provision\": {\n \"disclosure_language\": \"ja-JP\",\n \"version\": \"2026-01\"\n }\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_NOT_FOUND\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Revoke JP Consent
{
"title": "Revoke JP Consent",
"description": "Revokes a JP consent and returns the revoked state",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/revoke",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent revoked",
"body": "{\n \"consent_id\": \"cons_jp_1001\",\n \"status\": \"REVOKED\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Delete JP Consent
{
"title": "Delete JP Consent",
"description": "Deletes a JP consent through the alternate revoke path",
"method": "DELETE",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Consent revoked",
"body": "{\n \"consent_id\": \"cons_jp_1001\",\n \"status\": \"REVOKED\",\n \"revoked_at\": \"2026-01-15T12:00:00.000Z\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Exchange JP Consent Token
{
"title": "Exchange JP Consent Token",
"description": "Exchanges the authorization code for access and refresh tokens",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/token",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "json",
"requestBody": "{\n \"authorization_code\": \"ok\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Token exchange result",
"body": "{\n \"access_token\": \"acc_jp_1001\",\n \"refresh_token\": \"ref_jp_1001\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\",\n \"scope\": \"data:read data:write\"\n}"
},
"404": {
"description": "Consent not found",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_NOT_FOUND\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Refresh JP Access Token
{
"title": "Refresh JP Access Token",
"description": "Refreshes an access token and can trigger a reauth webhook when the refresh limit is exceeded",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/tokens/refresh",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"refresh_token\": \"ref_jp_1001\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Refreshed token pair",
"body": "{\n \"access_token\": \"acc_jp_2001\",\n \"refresh_token\": \"ref_jp_2001\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\",\n \"scope\": \"data:read data:write\"\n}"
},
"400": {
"description": "Refresh not allowed",
"body": "{\n \"error\": {\n \"code\": \"REFRESH_LIMIT_EXCEEDED\",\n \"message\": \"Refresh not allowed\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
},
"401": {
"description": "Partner auth required",
"body": "{\n \"error\": {\n \"code\": \"TOKEN_NOT_ALLOWED\",\n \"message\": \"Partner token required\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Introspect JP Token
{
"title": "Introspect JP Token",
"description": "Returns token activity and the consent scope attached to the token",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/tokens/introspect",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"token\": \"acc_jp_1001\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Token introspection result",
"body": "{\n \"active\": true,\n \"expires_at\": \"2026-01-01T13:00:00.000Z\",\n \"consent_id\": \"cons_jp_1001\",\n \"purpose\": \"PERSONAL_FINANCE\",\n \"data_categories\": [\n \"accounts\",\n \"balances\",\n \"transactions\",\n \"income\",\n \"cashflow_features\"\n ]\n}"
}
}
}
Get JP Accounts
{
"title": "Get JP Accounts",
"description": "Returns account records for the access-token consent context",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/data/accounts",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Account list",
"body": "{\n \"accounts\": [\n {\n \"account_id\": \"acct_jp_1001\",\n \"name\": \"Primary Checking\",\n \"type\": \"checking\",\n \"mask\": \"1234\",\n \"institution\": \"Financial Provider\"\n }\n ]\n}"
}
}
}
Get JP Consent Accounts
{
"title": "Get JP Consent Accounts",
"description": "Returns accounts for a consent-scoped path and rejects consent-token mismatches",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/data/accounts",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Account list",
"body": "{\n \"accounts\": [\n {\n \"account_id\": \"acct_jp_1001\",\n \"name\": \"Primary Checking\",\n \"type\": \"checking\",\n \"mask\": \"1234\",\n \"institution\": \"Financial Provider\"\n }\n ]\n}"
},
"403": {
"description": "Consent mismatch",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_MISMATCH\",\n \"message\": \"Consent ID does not match token\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get JP Balances
{
"title": "Get JP Balances",
"description": "Returns available and current balances for the access-token consent context",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/data/balances",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Balance list",
"body": "{\n \"balances\": [\n {\n \"account_id\": \"acct_jp_1001\",\n \"available\": 1250.5,\n \"current\": 1400.75,\n \"currency\": \"JPY\"\n }\n ]\n}"
}
}
}
Get JP Consent Balances
{
"title": "Get JP Consent Balances",
"description": "Returns balances for a consent-scoped path and rejects consent-token mismatches",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/data/balances",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Balance list",
"body": "{\n \"balances\": [\n {\n \"account_id\": \"acct_jp_1001\",\n \"available\": 1250.5,\n \"current\": 1400.75,\n \"currency\": \"JPY\"\n }\n ]\n}"
},
"403": {
"description": "Consent mismatch",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_MISMATCH\",\n \"message\": \"Consent ID does not match token\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get JP Transactions
{
"title": "Get JP Transactions",
"description": "Returns transactions filtered by date for the access-token consent context",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/data/transactions",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [
{
"key": "from",
"value": "2026-01-01",
"required": false
},
{
"key": "to",
"value": "2026-12-31",
"required": false
},
{
"key": "start_date",
"value": "2026-01-01",
"required": false
},
{
"key": "end_date",
"value": "2026-12-31",
"required": false
}
],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Transaction list",
"body": "{\n \"transactions\": [\n {\n \"transaction_id\": \"txn_jp_1001\",\n \"account_id\": \"acct_jp_1001\",\n \"posted_at\": \"2026-01-15T09:12:00Z\",\n \"amount\": -4200,\n \"currency\": \"JPY\",\n \"description\": \"Coffee Shop\",\n \"category\": \"food_and_drink\",\n \"type\": \"DEBIT\"\n }\n ]\n}"
}
}
}
Get JP Transaction Sync
{
"title": "Get JP Transaction Sync",
"description": "Returns a sync payload for transaction deltas",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/data/transactions/sync",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [
{
"key": "cursor",
"value": "demo",
"required": false
}
],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Transaction delta page",
"body": "{\n \"cursor\": \"cursor_1700000000000\",\n \"added\": [\n {\n \"transaction_id\": \"txn_jp_1001\",\n \"account_id\": \"acct_jp_1001\",\n \"posted_at\": \"2026-01-15T09:12:00Z\",\n \"amount\": -4200,\n \"currency\": \"JPY\",\n \"description\": \"Coffee Shop\",\n \"category\": \"food_and_drink\"\n }\n ],\n \"modified\": [\n {\n \"transaction_id\": \"txn_jp_1002\",\n \"account_id\": \"acct_jp_1001\",\n \"posted_at\": \"2026-01-16T09:12:00Z\",\n \"amount\": 180000,\n \"currency\": \"JPY\",\n \"description\": \"Payroll\",\n \"category\": \"income\"\n }\n ],\n \"removed\": [\n {\n \"transaction_id\": \"txn_jp_1003\"\n }\n ]\n}"
}
}
}
Get JP Consent Transactions
{
"title": "Get JP Consent Transactions",
"description": "Returns paginated transactions for a consent-scoped path",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/data/transactions",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [
{
"key": "from_date",
"value": "2026-01-01",
"required": false
},
{
"key": "to_date",
"value": "2026-01-31",
"required": false
},
{
"key": "limit",
"value": "25",
"required": false
},
{
"key": "cursor",
"value": "cur_0",
"required": false
}
],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Paginated transaction response",
"body": "{\n \"data\": [\n {\n \"transaction_id\": \"txn_jp_1001\",\n \"date\": \"2026-01-15\",\n \"amount\": -4200,\n \"currency\": \"JPY\",\n \"description\": \"Coffee Shop\",\n \"category\": \"food_and_drink\",\n \"type\": \"DEBIT\"\n }\n ],\n \"next_cursor\": \"cur_25\",\n \"total_count\": 1\n}"
},
"403": {
"description": "Consent mismatch or category denied",
"body": "{\n \"error\": {\n \"code\": \"CONSENT_MISMATCH\",\n \"message\": \"Consent ID does not match token\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get JP Income
{
"title": "Get JP Income",
"description": "Returns monthly income totals for the access-token consent context",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/data/income",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Income summary",
"body": "{\n \"method\": \"DIRECT\",\n \"gross_monthly\": 650000,\n \"net_monthly\": 520000,\n \"currency\": \"JPY\"\n}"
}
}
}
Get JP Consent Income
{
"title": "Get JP Consent Income",
"description": "Returns monthly income totals for a consent-scoped path",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/data/income",
"headers": [
{
"key": "Authorization",
"value": "Bearer <access_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Income summary",
"body": "{\n \"method\": \"DIRECT\",\n \"gross_monthly\": 650000,\n \"net_monthly\": 520000,\n \"currency\": \"JPY\"\n}"
}
}
}
Compute JP Features
{
"title": "Compute JP Features",
"description": "Computes cashflow features. When consent_id is present, the route runs in partner-auth job mode and returns 202; otherwise it runs in access-token direct mode and returns 200",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/features/compute",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token_or_access_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_id\": \"cons_jp_1001\",\n \"feature_set\": \"JP_CASHFLOW_V1\",\n \"as_of\": \"2026-01-15T00:00:00Z\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"202": {
"description": "Partner-auth job accepted",
"body": "{\n \"job_id\": \"job_a1b2c3d4e5f6\",\n \"status\": \"PROCESSING\",\n \"consent_id\": \"cons_jp_1001\",\n \"estimated_completion_ms\": 0\n}"
},
"200": {
"description": "Direct compute result",
"body": "{\n \"evidence_ref\": \"evidence_jp_1001\",\n \"features\": {\n \"monthly_income\": 520000,\n \"avg_balance\": 140075,\n \"overdraft_count\": 1,\n \"cashflow_surplus\": 145025,\n \"cashflow_inflow\": 480000,\n \"cashflow_outflow\": 334975,\n \"cashflow_net\": 145025\n }\n}"
}
}
}
Get JP Score
{
"title": "Get JP Score",
"description": "Replays the stored evidence through the scoring provider and returns the derived decision",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/score",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Score replay result",
"body": "{\n \"consent_id\": \"cons_jp_1001\",\n \"applicant_id\": \"app_jp_1001\",\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\": \"evidence_jp_1001\",\n \"scored_at\": \"2026-01-15T12:00:00.000Z\",\n \"model_version\": \"1.2.0\"\n}"
},
"422": {
"description": "Consent not active or score not ready",
"body": "{\n \"error\": {\n \"code\": \"consent_not_active\",\n \"message\": \"The consent cons_jp_1001 is not in ACTIVE status.\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
},
"502": {
"description": "Scoring provider unavailable",
"body": "{\n \"error\": {\n \"code\": \"provider_unavailable\",\n \"message\": \"Scoring provider error\",\n \"request_id\": \"req_123\",\n \"retryable\": true\n }\n}"
}
}
}
Get JP Evidence Replay
{
"title": "Get JP Evidence Replay",
"description": "Rebuilds a score input view from a stored evidence snapshot",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/evidence/:evidenceRef",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "evidenceRef",
"value": "evidence_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Evidence replay result",
"body": "{\n \"evidence_ref\": \"evidence_jp_1001\",\n \"consent_id\": \"cons_jp_1001\",\n \"applicant_id\": \"app_jp_1001\",\n \"snapshot_version\": \"1.2.0\",\n \"created_at\": \"2026-01-15T12:00:00.000Z\",\n \"score_inputs\": {\n \"payment_behavior\": {\n \"payments_observed\": 48,\n \"avg_payment_delay_days\": 2,\n \"late_payment_count_30d_plus\": 0\n },\n \"income\": {\n \"monthly_net_income\": 520000,\n \"income_stability_score\": 0.95\n },\n \"obligations\": {\n \"total_monthly_obligations\": 156000,\n \"obligation_to_income_ratio\": 0.3\n }\n },\n \"kyc_result\": {\n \"status\": \"PASSED\",\n \"checks\": [\n \"identity\",\n \"sanctions\",\n \"pep\"\n ]\n },\n \"delinquency_bucket\": \"CURRENT\",\n \"features\": {\n \"monthly_income\": 520000,\n \"avg_balance\": 140075,\n \"overdraft_count\": 1,\n \"cashflow_surplus\": 145025,\n \"cashflow_inflow\": 480000,\n \"cashflow_outflow\": 334975,\n \"cashflow_net\": 145025\n }\n}"
},
"404": {
"description": "Evidence not found",
"body": "{\n \"error\": {\n \"code\": \"EVIDENCE_NOT_FOUND\",\n \"message\": \"Evidence not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get JP KYC
{
"title": "Get JP KYC",
"description": "Returns the derived KYC and AML check status for a consent",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/consents/:consentId/kyc",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "cons_jp_1001",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "KYC result",
"body": "{\n \"consent_id\": \"cons_jp_1001\",\n \"status\": \"PASSED\",\n \"checks\": {\n \"identity\": {\n \"status\": \"PASSED\",\n \"method\": \"document_biometric\"\n },\n \"sanctions\": {\n \"status\": \"PASSED\",\n \"lists_screened\": [\n \"OFAC\",\n \"UN\",\n \"EU\"\n ]\n },\n \"pep\": {\n \"status\": \"PASSED\"\n },\n \"aml\": {\n \"status\": \"PASSED\",\n \"risk_level\": \"LOW\"\n }\n },\n \"completed_at\": \"2026-01-15T12:00:00.000Z\"\n}"
},
"422": {
"description": "Consent not active",
"body": "{\n \"error\": {\n \"code\": \"consent_not_active\",\n \"message\": \"Consent not active\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Get JP Job Status
{
"title": "Get JP Job Status",
"description": "Returns the in-memory job state for partner-auth feature compute requests",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/status/:jobId",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "jobId",
"value": "job_a1b2c3d4e5f6",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Job record",
"body": "{\n \"job_id\": \"job_a1b2c3d4e5f6\",\n \"status\": \"COMPLETE\",\n \"consent_id\": \"cons_jp_1001\",\n \"completed_at\": \"2026-01-15T12:00:00.000Z\",\n \"error\": null\n}"
},
"404": {
"description": "Job not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Job not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Replay JP Decision
{
"title": "Replay JP Decision",
"description": "Replays a stored evidence snapshot through the scoring service and returns the decision and reasons",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/api/v1/jp/decisions/replay",
"headers": [
{
"key": "Authorization",
"value": "Bearer <partner_token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"evidence_ref\": \"evidence_jp_1001\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Replay result",
"body": "{\n \"evidence_ref\": \"evidence_jp_1001\",\n \"decision\": \"APPROVE\",\n \"reasons\": [\n \"CONSISTENT_PAYMENT_HISTORY\"\n ]\n}"
},
"404": {
"description": "Evidence or consent not found",
"body": "{\n \"error\": {\n \"code\": \"EVIDENCE_NOT_FOUND\",\n \"message\": \"Evidence not found\",\n \"request_id\": \"req_123\",\n \"retryable\": false\n }\n}"
}
}
}
Webhook Delivery Service
The route modules fan out webhook notifications through listWebhookEndpoints and enqueueWebhookDelivery from @lita/webhooks. The emitWebhook helper is used in both regions, and the payloads are tenant-scoped.
| Event |
Trigger |
consent.activated |
After successful consent token exchange |
connection.created |
After successful consent token exchange |
consent.revoked |
After consent revocation |
connection.degraded |
When ensureConnection downgrades a stale active connection or before replay on stale paths |
connection.refreshed |
After touchConnection or touchJpConnection returns the refreshed connection |
connection.reauth_required |
When token refresh hits the refresh limit |
features.computed |
Partner-auth feature compute completes |
score.completed |
Feature compute or scoring completion in the region flow |
decision.completed |
Score replay returns a decision |
sequenceDiagram
participant H as Route handler
participant E as emitWebhook
participant L as listWebhookEndpoints
participant Q as enqueueWebhookDelivery
participant W as Webhook endpoints
H->>E: eventType plus payload
E->>L: tenantId
L-->>E: endpoints
loop every endpoint
E->>Q: tenantId endpointId eventType payload
Q-->>W: queued delivery
end
Request Logging
The route modules use the Fastify reply logger for two failure classes:
| Location |
Logged Data |
Purpose |
| Scoring callback catch block |
err plus the thrown error |
Captures provider callback failures |
emitWebhook catch block |
err plus eventType |
Captures webhook queueing failures |
The logging calls do not alter the HTTP response unless the surrounding handler chooses to return an error after catching the failure.
State Management
In-Memory Job Stores
| Store |
Type |
Use |
usJobStore |
Map<string, UsJobRecord> |
Tracks US partner-auth feature compute jobs |
jpJobStore |
Map<string, JpJobRecord> |
Tracks JP partner-auth feature compute jobs |
Connection Status Handling
ensureConnection reads the consent connection state and mutates stale active connections:
ACTIVE with a stale lastRefreshedAt value older than seven days is downgraded to DEGRADED
REAUTH_REQUIRED returns a 409 error with the reauth URL
DISCONNECTED returns a 409 provider-unavailable error
Status Values
- Consent status:
PENDING_USER_ACTION, ACTIVE, REVOKED
- Connection status:
ACTIVE, REAUTH_REQUIRED, DEGRADED, DISCONNECTED
- Job status:
PROCESSING, COMPLETE, FAILED
Error Handling
The route modules use the same error envelope shape and propagate request-scoped request.id values into the response. Errors are emitted with sendError, and the handlers return immediately after guard failures.
| Error Case |
Typical Status |
| Missing partner token |
401 |
| Missing access token |
401 |
| Consent mismatch |
403 |
| Category not allowed |
403 |
| Connection not found |
404 |
| Consent not found |
404 |
| Job not found |
404 |
| Consent not active |
422 |
| Scoring provider unavailable |
502 |
| Refresh limit exceeded |
400 |
| Revoked consent on refresh |
401 |
Dependencies
Route Module Dependencies
| Dependency |
Used By |
Purpose |
FastifyPluginAsync |
usRoutes, jpRoutes |
Route registration |
zod |
Both route modules |
Request and response schemas |
../../services/us-api.js |
US route module |
US consent, token, account, evidence, and connection operations |
../../services/jp-api.js |
JP route module |
JP consent, token, account, evidence, and connection operations |
../../services/partner-scoring.js |
Both route modules |
Score replay and decision retrieval |
@lita/webhooks |
Both route modules |
Webhook endpoint lookup and delivery queueing |
node:crypto |
Both route modules |
randomUUID for request IDs and job IDs |
process.env.API_PUBLIC_BASE_URL |
Consent create handlers |
Authorization redirect construction |
process.env.SCORING_CALLBACK_URL |
Score and replay handlers |
Fallback scoring callback configuration |
Executable Regional Surface
[!NOTE]
emitWebhook catches webhook fan-out failures, logs them with reply.log.error, and returns control to the handler without throwing. The request continues unless a later guard or business rule fails.
scripts/check-all-api-paths.sh validates the regional API surface by driving the same lifecycle in both regions. It starts with service readiness checks, then performs:
- US consent creation
- US token exchange
- US receipt, data, feature, score, KYC, evidence, replay, refresh, introspection, and revoke checks
- JP consent creation
- JP token exchange
- JP receipt, data, feature, score, KYC, evidence, replay, refresh, introspection, and revoke checks
The script uses curl and jq, records US_CONSENT, US_ACCESS, US_REFRESH, JP_CONSENT, JP_ACCESS, and JP_REFRESH, and exercises the exact regional paths under /api/v1/us and /api/v1/jp.
Key Classes Reference
| Class |
Responsibility |
us/index.ts |
US regional consent, token, data, scoring, KYC, evidence, and revocation routes |
jp/index.ts |
JP regional consent, token, data, scoring, KYC, evidence, and revocation routes |
check-all-api-paths.sh |
Executes the regional API smoke flow across both US and JP surfaces |