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, butHttpClient.baseRequestappliesDuration.ofSeconds(30)to every request. The configuredtimeoutonly reachesjava.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.codeerror.messageerror.request_iderror.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
createsends a JSON body with:applicant_idpurposedata_categoriesexpires_in_days
listTransactionsconverts:limitcursorfrom_dateto_date
into query parameters only when values are present.
get,revoke,getScore, andgetKycuse 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
Consent
[!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, andJobStatusResponse.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
Consent APIs
Create Consent
{
"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}"
}
}
}
Get Consent
{
"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}"
}
}
}
Revoke Consent
{
"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
Create Consent and Retrieve the Score
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:
- The caller builds
LitawithapiKeyandregion. ConsentsResource.create(...)serializes the request body fromConsentCreateParams.- The API returns a
Consentrecord with the redirect URL needed to complete the flow. - After activation,
ConsentsResource.getScore(...)fetches the computed score. - The score response carries the
evidenceRefused 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:
FeaturesResource.compute(...)submits the active consent ID.- The API responds immediately with a job ID and estimated completion window.
StatusResource.get(...)polls the job endpoint when polling is used.- The returned
JobStatusResponsecaptures 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:
- The application passes the raw request body without pre-parsing JSON.
Webhooks.constructEvent(...)computes the expected HMAC signature.- Constant-time comparison protects the signature check.
- 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.HttpClienthandles outbound transport.- Jackson
ObjectMapperhandles request and response JSON. Authorization: Bearer ...andX-Request-Idare attached to every request byHttpClient.Content-Type: application/jsonis added for body-bearing POST requests.Webhooks.constructEvent(...)validatesX-Lita-Signature.- Region routing is controlled by
Lita.Builder.region(String). - Sandbox routing is controlled by
Lita.Builder.sandbox(boolean). - The shared
HttpClient.MAPPERtolerates 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
ConsentCreateParamsandfeatures/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 |