Java: payment risk example
Observe a JDK HTTP service and record a synthetic payment-risk assessment.
#1. Install the Maven dependency
Add the portal-supplied Maven repository to your approved dependency process. The core SDK supports Java 8+. This example builds with Java 11 and requires neither Servlet nor Spring.
<dependency>
<groupId>io.sigillum</groupId>
<artifactId>finans-sdk</artifactId>
<version>0.11.0</version>
</dependency>package example;
import io.sigillum.finans.*;
import com.sun.net.httpserver.HttpServer;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.InetSocketAddress;
import java.nio.file.Paths;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;
public final class PaymentDemo {
public static void main(String[] args) throws Exception {
String path = System.getenv("SIGILLUM_CONFIG");
if (path == null) throw new IllegalArgumentException("SIGILLUM_CONFIG must be set");
Sigillum sdk = Sigillum.start(Paths.get(path).toAbsolutePath());
ObjectMapper json = new ObjectMapper();
HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 5109), 0);
server.createContext("/payments/assess", sdk.httpHandler(exchange -> {
if (!"POST".equals(exchange.getRequestMethod())) {
exchange.sendResponseHeaders(405, -1); exchange.close(); return;
}
byte[] raw = exchange.getRequestBody().readNBytes(8193);
if (raw.length > 8192) { exchange.sendResponseHeaders(413, -1); exchange.close(); return; }
var input = json.readTree(raw);
try (ObservationScope step = sdk.child("payment-rule");
Sigillum.Binding current = step.activate()) {
double amount = input.path("amount").asDouble(-1);
if (amount <= 0) { exchange.sendResponseHeaders(400, -1); exchange.close(); return; }
// Synthetic threshold rule: not a production risk model or financial advice.
Map<String,Object> result = new LinkedHashMap<>();
result.put("requestRef", input.path("requestRef").asText("DEMO-PAYMENT"));
result.put("amount", amount);
result.put("reviewRequired", amount > 10000);
result.put("demonstration", true);
sdk.ai("policy", "{\"name\":\"demo-amount-threshold\",\"threshold\":10000}".getBytes(StandardCharsets.UTF_8));
sdk.ai("explanation", "{\"method\":\"deterministic-demo\",\"rule\":\"amount > 10000\"}".getBytes(StandardCharsets.UTF_8));
byte[] response = json.writeValueAsBytes(result);
sdk.capture("custom", "payment.result", response);
sdk.capture(sdk.current(), "source", "comparison.source", "demo.payment/1",
"{\"type\":\"demo-result\"}".getBytes(StandardCharsets.UTF_8),
new CaptureContent("result", "application/json", "comparison.originalContent", response));
exchange.getResponseHeaders().set("Content-Type", "application/json");
exchange.sendResponseHeaders(200, response.length);
exchange.getResponseBody().write(response);
} finally { exchange.close(); }
}));
server.createContext("/sdk-status", exchange -> {
byte[] response = sdk.diagnostics().toString().getBytes(StandardCharsets.UTF_8);
exchange.sendResponseHeaders(200, response.length);
exchange.getResponseBody().write(response); exchange.close();
});
server.start();
System.out.println("Demo: http://127.0.0.1:5109 — SDK diagnostics: /sdk-status");
}
}
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion><groupId>example.sigillum</groupId><artifactId>payment-demo</artifactId><version>1.0.0</version>
<properties><maven.compiler.release>11</maven.compiler.release><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties>
<dependencies><dependency><groupId>io.sigillum</groupId><artifactId>finans-sdk</artifactId><version>0.11.0</version></dependency></dependencies>
<build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.13.0</version></plugin><plugin><groupId>org.codehaus.mojo</groupId><artifactId>exec-maven-plugin</artifactId><version>3.5.0</version><configuration><mainClass>example.PaymentDemo</mainClass></configuration></plugin></plugins></build>
</project>#2. Start the SDK and wrap HTTP
Create one SDK per service using Sigillum.start(absolutePath). Wrap a JDK HttpServer handler with sigillum.httpHandler(nativeHandler). Use httpConnection for Java 8 outbound connections or httpClient for Java 11+. Unsupported third-party clients are not automatically observed.
#3. Record payment-risk assessment
The POST /payments/assess example accepts an amount and a request reference. The local assessment runs in a child scope. Explicit calls record the applied policy, explanation, business result and original source attachment. Additional AI categories are demonstrated separately in the AI observation examples. No payment is executed.
#4. Add data and attachments
Use convenience calls such as sigillum.ai("model", modelJson). The general interface is capture(context, family, kind, schema, rawJson, contents...). CaptureContent(id, mediaType, purpose, bytes) carries original content. SpanLink must refer to an actual trace/span relationship.
#5. Propagate callback context
wrap(Runnable) and wrap(Callable) carry context across an actual executor boundary. activate(context) restores the previous context when the scope closes. Do not merge independent work because it shares a customer reference. The SDK does not replace the application’s global OTEL provider.
#6. Run the project
Follow the ZIP README to install the supplied Maven artifacts, set SIGILLUM_CONFIG to the absolute configuration path and start the application. For Servlet applications, use the Servlet adapters guide.