Java SDK HTTP Layer, Models, Params, and Resources

Overview

The Java SDK is the official typed client for the Lita API surface that lives in sdks/java. It centers on a builder-based Lita entry point that wires a shared HTTP transport into four resource groups: consents, features, evidence, and status. The client is region-aware, supports sandbox routing, and always injects the authentication and request-correlation headers used by the API.

The SDK is designed around request/response models rather than loose maps. Consent creation, score retrieval, evidence snapshots, KYC results, async job polling, and transaction listing each map to dedicated Java model classes, while webhook verification is handled by a separate HMAC helper. The result is a surface that is compact for callers but explicit about payload shape, error handling, and signature verification.

Architecture Overview

flowchart TB
    subgraph JavaSdk [Java SDK]
        LitaFacade[Lita]
        Builder[Builder]
        Resources[Resource Layer]
        HttpTransport[HttpClient]
        WebhookHelper[Webhooks]
        Params[Params Models]
        DomainModels[Response Models]
        Errors[LitaException and LitaWebhookSignatureException]
    end

    subgraph ExternalApi [Join Lita API]
        ApiSurface[Regional API Surface]
    end

    Builder --> LitaFacade
    LitaFacade --> Resources
    Resources --> HttpTransport
    HttpTransport --> ApiSurface
    HttpTransport --> DomainModels
    HttpTransport --> Errors
    WebhookHelper --> Errors
    WebhookHelper --> DomainModels
    Resources --> Params

Project Metadata and Dependencies

Maven Project Metadata

sdks/java/pom.xml

The Maven project defines the Java SDK artifact and its runtime/test dependencies.

Property Value
groupId com.joinlita
artifactId lita-java
version 1.2.0
packaging jar
name Lita Java SDK
description Official Lita Java SDK for the Global Credit Portability Infrastructure API
url https://github.com/joinlita/lita-java
license MIT License
java.version 11
Dependency Purpose
com.fasterxml.jackson.core:jackson-databind JSON serialization and deserialization
com.fasterxml.jackson.datatype:jackson-datatype-jsr310 Java time support
org.junit.jupiter:junit-jupiter Test framework

The build uses maven-surefire-plugin for test execution.

Client Facade

Lita

sdks/java/src/main/java/com/joinlita/Lita.java

Lita is the main SDK entry point. It owns the shared HttpClient instance and exposes the four resource facades used by callers.

Properties

Property Type Description
consents ConsentsResource Consent creation, lookup, revocation, score retrieval, transaction listing, and KYC lookup
features FeaturesResource Feature computation trigger
evidence EvidenceResource Evidence snapshot retrieval
status StatusResource Async job status polling

Methods

Method Description
consents Returns the consent-related resource facade
features Returns the feature computation resource facade
evidence Returns the evidence retrieval resource facade
status Returns the job status resource facade
builder Returns a new Builder instance

Builder

sdks/java/src/main/java/com/joinlita/Lita.java

Builder captures client configuration before the SDK constructs the shared HTTP transport.

Properties

Property Type Description
apiKey String Bearer token used in the Authorization header
region String Target region segment, documented as "us" or "jp"
baseUrl String Override for the default API base URL
timeout Duration Configuration passed into the HTTP client builder
sandbox boolean Toggles sandbox routing under the region path

Methods

Method Description
apiKey Captures the API key for later client construction
region Captures the region for later client construction
sandbox Enables sandbox routing for the regional API path
baseUrl Overrides the default API base URL
timeout Captures the timeout configuration
build Creates the Lita client and its shared resources

Construction and wiring

Type Description
Builder Supplies apiKey, region, baseUrl, timeout, and sandbox
HttpClient Created internally from the builder values and shared across all resources

HTTP Transport

HttpClient

[!IMPORTANT] Lita.Builder.timeout(Duration) is documented as the HTTP request timeout, but HttpClient.baseRequest applies Duration.ofSeconds(30) to every request. The configured timeout only reaches java.net.http.HttpClient.newBuilder().connectTimeout(...), so request timeout behavior does not follow the builder value.

sdks/java/src/main/java/com/joinlita/HttpClient.java

HttpClient is the internal transport layer used by every resource class. It composes URLs from the base URL, region prefix, and resource path, attaches request headers, serializes request bodies, and maps API errors into LitaException.

Properties

Property Type Description
apiKey String Token inserted into the Authorization header
regionPrefix String region or region/sandbox depending on the builder flag
baseUrl String Base API URL with any trailing slash removed
httpClient java.net.http.HttpClient JDK HTTP transport instance configured with connect timeout
MAPPER ObjectMapper Shared Jackson mapper configured with FAIL_ON_UNKNOWN_PROPERTIES = false

Methods

Method Visibility Description
get package-private Sends a GET request without query parameters
get package-private Sends a GET request with encoded query parameters
post package-private Serializes a body to JSON and sends a POST request
delete package-private Sends a DELETE request
baseRequest private Builds the request with Authorization, X-Request-Id, and timeout headers
execute private Sends the request, decodes successful JSON, and maps non-2xx responses to LitaException

Transport behavior

  • URL construction follows baseUrl + "/" + regionPrefix + "/" + path.
  • Sandbox routing changes the region prefix to region/sandbox.
  • Query parameters are URL-encoded and null values are skipped.
  • POST requests add Content-Type: application/json.
  • Every request includes:
    • Authorization: Bearer <apiKey>
    • X-Request-Id: req-<UUID>
  • Successful responses are decoded with the shared Jackson mapper.
  • Error responses are parsed as JSON and converted into LitaException.

Error mapping

execute reads the response body as a JSON map when the status code is 400 or higher. It extracts:

  • error.code
  • error.message
  • error.request_id
  • error.retryable

Those values are passed into LitaException.

Webhooks

sdks/java/src/main/java/com/joinlita/Webhooks.java

Webhooks provides signature verification for incoming webhook payloads. It uses HMAC-SHA256 over the raw request body and compares the computed signature to the X-Lita-Signature header in constant time.

Properties

Property Type Description
MAPPER ObjectMapper Shared mapper reused from HttpClient for parsing webhook payloads

Methods

Method Description
constructEvent(byte[], String, String) Verifies the signature, parses the raw JSON body, and returns the event payload as a Map<String, Object>
constructEvent(String, String, String) UTF-8 convenience overload that delegates to the byte-array variant

Verification behavior

  • The expected signature format is sha256=<hex>.
  • The comparison uses MessageDigest.isEqual(...) for constant-time comparison.
  • A mismatch throws LitaWebhookSignatureException.
  • JSON parsing happens only after signature verification succeeds.

Error Types

LitaException

sdks/java/src/main/java/com/joinlita/LitaException.java

LitaException is the SDK’s runtime wrapper for non-2xx API responses.

Properties

Property Type Description
statusCode int HTTP status returned by the API
errorCode String Machine-readable API error code
requestId String X-Request-Id captured from the failing request context
retryable boolean Retry hint forwarded from the API error payload

Methods

Method Description
getStatusCode Returns the HTTP status code
getErrorCode Returns the machine-readable error code
getRequestId Returns the request identifier attached to the failing request
isRetryable Returns the retry hint
toString Produces a diagnostic string containing all captured fields

LitaWebhookSignatureException

sdks/java/src/main/java/com/joinlita/LitaWebhookSignatureException.java

LitaWebhookSignatureException is thrown when webhook signature verification fails in Webhooks.constructEvent(...). The class only supplies the fixed failure message used by the SDK.

Resource Layer

ConsentsResource

sdks/java/src/main/java/com/joinlita/resources/ConsentsResource.java

ConsentsResource wraps the consent, score, transaction, and KYC endpoints that hang off an existing regional API client.

Constructor Dependencies

Type Description
HttpClient Shared transport used for every consent-related request

Properties

Property Type Description
http HttpClient Shared transport instance

Methods

Method Description
create Creates a consent from ConsentCreateParams and returns Consent
get Fetches the current consent state by consent ID and returns Consent
revoke Revokes a consent by consent ID and returns Consent
getScore Fetches the computed score for a consent and returns Score
listTransactions Convenience overload that lists transactions without filters and returns TransactionListResponse
listTransactions Lists transactions with optional filters from TransactionListParams and returns TransactionListResponse
getKyc Fetches KYC and AML results for a consent and returns KycResult

Request mapping

  • create sends a JSON body with:
    • applicant_id
    • purpose
    • data_categories
    • expires_in_days
  • listTransactions converts:
    • limit
    • cursor
    • from_date
    • to_date

into query parameters only when values are present.

  • get, revoke, getScore, and getKyc use consent ID path segments.

Evidence and audit linkage

The consent resource is the gateway to:

  • consent state records
  • computed scores
  • paginated transaction data
  • KYC compliance payloads

EvidenceResource

sdks/java/src/main/java/com/joinlita/resources/EvidenceResource.java

EvidenceResource exposes immutable evidence snapshots for audit and compliance workflows.

Constructor Dependencies

Type Description
HttpClient Shared transport used for evidence retrieval

Properties

Property Type Description
http HttpClient Shared transport instance

Methods

Method Description
get Retrieves an evidence snapshot by evidence reference and returns EvidenceSnapshot

FeaturesResource

sdks/java/src/main/java/com/joinlita/resources/FeaturesResource.java

FeaturesResource triggers the asynchronous feature computation pipeline.

Constructor Dependencies

Type Description
HttpClient Shared transport used for feature computation requests

Properties

Property Type Description
http HttpClient Shared transport instance

Methods

Method Description
compute Starts feature computation for an active consent and returns ComputeFeaturesResponse

StatusResource

sdks/java/src/main/java/com/joinlita/resources/StatusResource.java

StatusResource polls the status of async jobs created by feature computation.

Constructor Dependencies

Type Description
HttpClient Shared transport used for status polling

Properties

Property Type Description
http HttpClient Shared transport instance

Methods

Method Description
get Polls a job status by job ID and returns JobStatusResponse

Params

ConsentCreateParams

sdks/java/src/main/java/com/joinlita/params/ConsentCreateParams.java

ConsentCreateParams is the builder-based request object used by ConsentsResource.create(...).

Properties

Property Type Description
applicantId String Applicant identifier sent as applicant_id
purpose String Consent purpose sent as purpose
dataCategories List<String> Data categories sent as data_categories
expiresInDays int Active window in days sent as expires_in_days

Methods

Method Description
builder Returns a new Builder instance
getApplicantId Returns the applicant ID
getPurpose Returns the purpose string
getDataCategories Returns the category list
getExpiresInDays Returns the active window in days

Builder methods

Method Description
applicantId Captures the applicant identifier
purpose Captures the consent purpose
dataCategories Captures the requested data categories
expiresInDays Captures the active window in days
build Creates the immutable request object

TransactionListParams

sdks/java/src/main/java/com/joinlita/params/TransactionListParams.java

TransactionListParams carries optional query parameters for transaction listing.

Properties

Property Type Description
limit Integer Optional page size
cursor String Optional pagination cursor
fromDate String Optional ISO 8601 date string used as from_date
toDate String Optional ISO 8601 date string used as to_date

Methods

Method Description
builder Returns a new Builder instance
getLimit Returns the limit
getCursor Returns the cursor
getFromDate Returns the lower date bound
getToDate Returns the upper date bound

Builder methods

Method Description
limit Captures the page size
cursor Captures the pagination cursor
fromDate Captures the lower date bound
toDate Captures the upper date bound
build Creates the immutable query object

Models

[!NOTE] The Java SDK uses strongly typed top-level models for the main API entities, while several nested response sections remain map-typed in Java: Score.scoreRange, EvidenceSnapshot.scoreInputs, EvidenceSnapshot.kycResult, KycResult.checks, and JobStatusResponse.error.

sdks/java/src/main/java/com/joinlita/model/Consent.java

Property Type Description
consentId String Consent identifier
status String Consent lifecycle state returned by the API
applicantId String Applicant identifier
purpose String Purpose attached to the consent
redirectUrl String Redirect URL used to complete the consent flow
createdAt String Creation timestamp
activatedAt String Activation timestamp
expiresAt String Expiration timestamp
revokedAt String Revocation timestamp
connections List<Connection> Linked external connections

Connection

sdks/java/src/main/java/com/joinlita/model/Connection.java

Property Type Description
connectionId String Connection identifier
provider String External provider name
status String Connection state

Score

sdks/java/src/main/java/com/joinlita/model/Score.java

Property Type Description
consentId String Consent identifier associated with the score
applicantId String Applicant identifier associated with the score
score int Numeric score value
scoreRange Map<String, Integer> Score bounds from the API payload
decision String Underwriting decision
scoreFactors List<String> Ordered list of score drivers
evidenceRef String Evidence reference used for audit retrieval
scoredAt String Score timestamp
modelVersion String Model version string

EvidenceSnapshot

sdks/java/src/main/java/com/joinlita/model/EvidenceSnapshot.java

Property Type Description
evidenceRef String Evidence reference
consentId String Consent identifier
applicantId String Applicant identifier
snapshotVersion String Snapshot version string
createdAt String Snapshot creation timestamp
scoreInputs Map<String, Object> Score input payload grouped by input domain
kycResult Map<String, Object> Embedded KYC result payload
delinquencyBucket String Delinquency bucket string

KycResult

sdks/java/src/main/java/com/joinlita/model/KycResult.java

Property Type Description
consentId String Consent identifier
status String KYC or AML status
checks Map<String, Map<String, Object>> Per-check details keyed by check name
completedAt String Completion timestamp

JobStatusResponse

sdks/java/src/main/java/com/joinlita/model/JobStatusResponse.java

Property Type Description
jobId String Async job identifier
status String Job state
consentId String Consent identifier associated with the job
completedAt String Completion timestamp
error Map<String, String> Error details for failed jobs

ComputeFeaturesResponse

sdks/java/src/main/java/com/joinlita/model/ComputeFeaturesResponse.java

Property Type Description
jobId String Async job identifier
status String Job state returned after submission
consentId String Consent identifier submitted for processing
estimatedCompletionMs int Estimated time until completion

TransactionListResponse

sdks/java/src/main/java/com/joinlita/model/TransactionListResponse.java

Property Type Description
data List<Transaction> Page of transaction records
nextCursor String Cursor for the next page
totalCount int Total number of transactions in the result set

Transaction

sdks/java/src/main/java/com/joinlita/model/Transaction.java

Property Type Description
transactionId String Transaction identifier
date String Transaction date
amount double Transaction amount
currency String ISO currency code
description String Transaction description
category String Transaction category
type String Transaction direction or type

API Integration

{
    "title": "Create Consent",
    "description": "Creates a consent for an applicant and returns the consent record with redirect_url. Sandbox mode inserts /sandbox after the region segment.",
    "method": "POST",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"data_categories\": [\n        \"transactions\",\n        \"income\",\n        \"payment_behavior\"\n    ],\n    \"expires_in_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_123\",\n    \"status\": \"PENDING\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"redirect_url\": \"https://app.joinlita.com/consents/con_123\",\n    \"created_at\": \"2025-01-10T12:00:00Z\",\n    \"activated_at\": null,\n    \"expires_at\": \"2025-02-09T12:00:00Z\",\n    \"revoked_at\": null,\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_001\",\n            \"provider\": \"bank_x\",\n            \"status\": \"CONNECTED\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Get Consent",
    "description": "Fetches the current consent state by consent ID. Sandbox mode inserts /sandbox after the region segment.",
    "method": "GET",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/consents/{consentId}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "con_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_123\",\n    \"status\": \"ACTIVE\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"redirect_url\": \"https://app.joinlita.com/consents/con_123\",\n    \"created_at\": \"2025-01-10T12:00:00Z\",\n    \"activated_at\": \"2025-01-10T12:05:00Z\",\n    \"expires_at\": \"2025-02-09T12:00:00Z\",\n    \"revoked_at\": null,\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_001\",\n            \"provider\": \"bank_x\",\n            \"status\": \"CONNECTED\"\n        }\n    ]\n}"
        }
    }
}
{
    "title": "Revoke Consent",
    "description": "Revokes an active consent by consent ID and returns the updated consent record. Sandbox mode inserts /sandbox after the region segment.",
    "method": "DELETE",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/consents/{consentId}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "con_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_123\",\n    \"status\": \"REVOKED\",\n    \"applicant_id\": \"app_demo_001\",\n    \"purpose\": \"LENDING_UNDERWRITING\",\n    \"redirect_url\": \"https://app.joinlita.com/consents/con_123\",\n    \"created_at\": \"2025-01-10T12:00:00Z\",\n    \"activated_at\": \"2025-01-10T12:05:00Z\",\n    \"expires_at\": \"2025-02-09T12:00:00Z\",\n    \"revoked_at\": \"2025-01-11T08:30:00Z\",\n    \"connections\": [\n        {\n            \"connection_id\": \"conn_001\",\n            \"provider\": \"bank_x\",\n            \"status\": \"CONNECTED\"\n        }\n    ]\n}"
        }
    }
}

Get Score

{
    "title": "Get Score",
    "description": "Retrieves the computed score for a consent by consent ID. Sandbox mode inserts /sandbox after the region segment.",
    "method": "GET",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/consents/{consentId}/score",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "con_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_123\",\n    \"applicant_id\": \"app_demo_001\",\n    \"score\": 742,\n    \"score_range\": {\n        \"min\": 300,\n        \"max\": 850\n    },\n    \"decision\": \"APPROVE\",\n    \"score_factors\": [\n        \"income_stability\",\n        \"low_utilization\",\n        \"no_recent_delinquencies\"\n    ],\n    \"evidence_ref\": \"evi_123\",\n    \"scored_at\": \"2025-01-10T12:07:00Z\",\n    \"model_version\": \"2025.01\"\n}"
        }
    }
}

List Transactions

{
    "title": "List Transactions",
    "description": "Lists paginated transactions for a consent, applying optional limit, cursor, from_date, and to_date query filters. Sandbox mode inserts /sandbox after the region segment.",
    "method": "GET",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/consents/{consentId}/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "limit",
            "value": "50",
            "required": false
        },
        {
            "key": "cursor",
            "value": "eyJwYWdlIjoyfQ==",
            "required": false
        },
        {
            "key": "from_date",
            "value": "2025-01-01",
            "required": false
        },
        {
            "key": "to_date",
            "value": "2025-01-31",
            "required": false
        }
    ],
    "pathParams": [
        {
            "key": "consentId",
            "value": "con_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"data\": [\n        {\n            \"transaction_id\": \"txn_001\",\n            \"date\": \"2025-01-15\",\n            \"amount\": 124.56,\n            \"currency\": \"USD\",\n            \"description\": \"Payroll deposit\",\n            \"category\": \"income\",\n            \"type\": \"CREDIT\"\n        }\n    ],\n    \"next_cursor\": \"eyJwYWdlIjoyfQ==\",\n    \"total_count\": 1\n}"
        }
    }
}

Get KYC Result

{
    "title": "Get KYC Result",
    "description": "Returns the KYC and AML compliance check result for a consent. Sandbox mode inserts /sandbox after the region segment.",
    "method": "GET",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/consents/{consentId}/kyc",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consentId",
            "value": "con_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"con_123\",\n    \"status\": \"PASSED\",\n    \"checks\": {\n        \"identity\": {\n            \"status\": \"PASSED\",\n            \"method\": \"document_and_selfie\",\n            \"lists_screened\": [\n                \"sanctions\",\n                \"pep\"\n            ],\n            \"risk_level\": \"low\"\n        },\n        \"sanctions\": {\n            \"status\": \"CLEAR\",\n            \"method\": \"watchlist\",\n            \"lists_screened\": [\n                \"ofac\"\n            ],\n            \"risk_level\": \"low\"\n        },\n        \"pep\": {\n            \"status\": \"CLEAR\",\n            \"method\": \"watchlist\",\n            \"lists_screened\": [\n                \"pep\"\n            ],\n            \"risk_level\": \"low\"\n        },\n        \"aml\": {\n            \"status\": \"CLEAR\",\n            \"method\": \"monitoring\",\n            \"lists_screened\": [\n                \"aml\"\n            ],\n            \"risk_level\": \"low\"\n        }\n    },\n    \"completed_at\": \"2025-01-10T12:10:00Z\"\n}"
        }
    }
}

Evidence API

Get Evidence Snapshot

{
    "title": "Get Evidence Snapshot",
    "description": "Retrieves an immutable evidence snapshot for audit trails, adverse action notices, and regulatory responses. Sandbox mode inserts /sandbox after the region segment.",
    "method": "GET",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/evidence/{evidenceRef}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "evidenceRef",
            "value": "evi_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"evidence_ref\": \"evi_123\",\n    \"consent_id\": \"con_123\",\n    \"applicant_id\": \"app_demo_001\",\n    \"snapshot_version\": \"v1\",\n    \"created_at\": \"2025-01-10T12:07:00Z\",\n    \"score_inputs\": {\n        \"payment_behavior\": {\n            \"payments_observed\": 12,\n            \"avg_payment_delay_days\": 1.4,\n            \"late_payment_count_30d_plus\": 0\n        },\n        \"income\": {\n            \"monthly_net_income\": 4500,\n            \"income_stability_score\": 82\n        },\n        \"obligations\": {\n            \"total_monthly_obligations\": 1100,\n            \"obligation_to_income_ratio\": 0.24\n        }\n    },\n    \"kyc_result\": {\n        \"status\": \"PASSED\",\n        \"checks\": [\n            \"identity\",\n            \"sanctions\",\n            \"pep\",\n            \"aml\"\n        ]\n    },\n    \"delinquency_bucket\": \"CURRENT\"\n}"
        }
    }
}

Feature APIs

Compute Features

{
    "title": "Compute Features",
    "description": "Starts the asynchronous feature computation pipeline for an active consent. Sandbox mode inserts /sandbox after the region segment.",
    "method": "POST",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/features/compute",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_id\": \"con_123\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"job_id\": \"job_123\",\n    \"status\": \"PROCESSING\",\n    \"consent_id\": \"con_123\",\n    \"estimated_completion_ms\": 45000\n}"
        }
    }
}

Job Status API

Get Job Status

{
    "title": "Get Job Status",
    "description": "Polls the status of an async processing job. Sandbox mode inserts /sandbox after the region segment.",
    "method": "GET",
    "baseUrl": "<JavaSdkBaseUrl>",
    "endpoint": "/{region}/status/{jobId}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <apiKey>",
            "required": true
        },
        {
            "key": "X-Request-Id",
            "value": "req-<uuid>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "jobId",
            "value": "job_123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"job_id\": \"job_123\",\n    \"status\": \"COMPLETE\",\n    \"consent_id\": \"con_123\",\n    \"completed_at\": \"2025-01-10T12:11:00Z\",\n    \"error\": []\n}"
        }
    }
}

Feature Flows

sequenceDiagram
    participant App as Application
    participant Lita as Lita
    participant Consents as ConsentsResource
    participant Http as HttpClient
    participant Api as Join Lita API

    App->>Lita: builder apiKey region build
    App->>Consents: create ConsentCreateParams
    Consents->>Http: post consents body
    Http->>Api: POST regional consents request
    Api-->>Http: Consent JSON
    Http-->>Consents: Consent
    Consents-->>App: Consent with redirectUrl

    App->>Consents: getScore consentId
    Consents->>Http: get consents consentId score
    Http->>Api: GET regional score request
    Api-->>Http: Score JSON
    Http-->>Consents: Score
    Consents-->>App: Score decision and evidenceRef

Flow details:

  1. The caller builds Lita with apiKey and region.
  2. ConsentsResource.create(...) serializes the request body from ConsentCreateParams.
  3. The API returns a Consent record with the redirect URL needed to complete the flow.
  4. After activation, ConsentsResource.getScore(...) fetches the computed score.
  5. The score response carries the evidenceRef used to retrieve audit evidence later.

Trigger Feature Computation and Poll Job Status

sequenceDiagram
    participant App as Application
    participant Features as FeaturesResource
    participant Status as StatusResource
    participant Http as HttpClient
    participant Api as Join Lita API

    App->>Features: compute consentId
    Features->>Http: post features compute body
    Http->>Api: POST regional features compute
    Api-->>Http: ComputeFeaturesResponse JSON
    Http-->>Features: ComputeFeaturesResponse
    Features-->>App: jobId and estimatedCompletionMs

    loop until complete
        App->>Status: get jobId
        Status->>Http: get status jobId
        Http->>Api: GET regional status request
        Api-->>Http: JobStatusResponse JSON
        Http-->>Status: JobStatusResponse
        Status-->>App: status and completedAt
    end

Flow details:

  1. FeaturesResource.compute(...) submits the active consent ID.
  2. The API responds immediately with a job ID and estimated completion window.
  3. StatusResource.get(...) polls the job endpoint when polling is used.
  4. The returned JobStatusResponse captures completion metadata and any job-level error details.

Verify a Webhook Event

sequenceDiagram
    participant Api as Join Lita API
    participant App as Application
    participant Webhooks as Webhooks

    Api-->>App: webhook delivery with raw body and X Lita Signature
    App->>Webhooks: constructEvent rawBody signature secret
    Webhooks->>Webhooks: HmacSHA256 and constant time compare

    alt signature matches
        Webhooks-->>App: parsed event map
    else signature mismatch
        Webhooks-->>App: LitaWebhookSignatureException
    end

Flow details:

  1. The application passes the raw request body without pre-parsing JSON.
  2. Webhooks.constructEvent(...) computes the expected HMAC signature.
  3. Constant-time comparison protects the signature check.
  4. On success, the method returns the parsed payload map.

State Management

The Java SDK keeps state in a small number of explicit places:

State Area Representation Notes
Client configuration Lita.Builder fields Captures API key, region, base URL, timeout, and sandbox flag before client construction
Routing state regionPrefix in HttpClient Switches between region and region/sandbox
Consent lifecycle Consent.status Server-authored consent state returned by the API
Score outcome Score.decision Server-authored decision string
KYC outcome KycResult.status Server-authored KYC state
Job lifecycle JobStatusResponse.status Server-authored async job state

The SDK itself does not mutate these domain objects after deserialization. Instead, the resource methods return the latest server state on each call.

Integration Points

  • java.net.http.HttpClient handles outbound transport.
  • Jackson ObjectMapper handles request and response JSON.
  • Authorization: Bearer ... and X-Request-Id are attached to every request by HttpClient.
  • Content-Type: application/json is added for body-bearing POST requests.
  • Webhooks.constructEvent(...) validates X-Lita-Signature.
  • Region routing is controlled by Lita.Builder.region(String).
  • Sandbox routing is controlled by Lita.Builder.sandbox(boolean).
  • The shared HttpClient.MAPPER tolerates unknown JSON fields during decoding.

Error Handling

Error Type Where It Comes From Behavior
LitaException HttpClient.execute(...) on response status >= 400 Wraps API error metadata including status code, machine-readable code, request ID, and retry hint
IOException Transport failures or interrupted requests Propagated from the HTTP client, with interrupted threads re-interrupted before wrapping
LitaWebhookSignatureException Webhooks.constructEvent(...) signature mismatch Thrown when the computed HMAC does not match X-Lita-Signature
RuntimeException Webhook HMAC or payload parse failures Used for unrecoverable signature or parsing problems

The API error path extracts error.code, error.message, error.request_id, and error.retryable when the response payload includes an error object. LitaException.toString() preserves those details for diagnostics.

Testing Considerations

The Java SDK’s Maven configuration points at JUnit 5, which fits the code paths that matter most in this section:

  • client construction from Lita.Builder
  • region and sandbox URL composition
  • request header injection
  • query parameter encoding in TransactionListParams
  • JSON body serialization in ConsentCreateParams and features/compute
  • non-2xx mapping into LitaException
  • HMAC verification and mismatch handling in Webhooks
  • response model decoding for consent, score, evidence, KYC, job, and transaction payloads

Key Classes Reference

Class Responsibility
Lita.java Builder-based SDK entry point and resource factory
HttpClient.java Internal transport, header injection, URL composition, and error mapping
Webhooks.java Webhook signature verification and payload parsing
LitaException.java API error wrapper for non-2xx responses
LitaWebhookSignatureException.java Thrown when webhook signature verification fails
ConsentsResource.java Consent, score, transaction, and KYC endpoints
EvidenceResource.java Evidence snapshot endpoint
FeaturesResource.java Async feature computation endpoint
StatusResource.java Async job status endpoint
ConsentCreateParams.java Consent creation request builder
TransactionListParams.java Transaction listing query builder
Consent.java Consent response model
Connection.java Nested consent connection model
Score.java Score response model
EvidenceSnapshot.java Evidence snapshot response model
KycResult.java KYC and AML response model
JobStatusResponse.java Async job status response model
ComputeFeaturesResponse.java Feature compute submission response model
TransactionListResponse.java Transaction list response wrapper
Transaction.java Transaction item model