Skip to main content

Inttegro Java SDK

The Inttegro Java SDK builds server-side integrations with typed request builders, domain objects and enums, and Java's native HttpClient. A configured client can be shared safely across threads.

Start with MCP

Before writing SDK code, connect your MCP client and ask MCP to design the integration for your Java application. Use the resulting implementation and test plan to guide the code you write with this SDK.

Install

The SDK requires Java 17 or newer. Maven Central publication is being configured; until it is available, use the signed release artifacts on GitHub.

Keep the SDK on the server

Load the secret API key securely from server-side code. Never package the key in a desktop or mobile application, browser code, or source control.

Create a client

import com.inttegro.Client;

public class Example {
    public static void main(String[] args) {
        Client inttegro = new Client(System.getenv("INTTEGRO_API_KEY"));
    }
}

Resource clients use methods such as orders(), customers(), and refunds(). Request types expose fluent builders for their supported fields.

See it in a complete app

The Spring Boot invoice portal demo shows how a service business can give clients a clear place to review and pay outstanding invoices. Follow the guide to see the Java SDK create the order behind a Spring MVC checkout and hand payment to Inttegro Checkout.

Observability

Java's global OpenTelemetry instance is used automatically. Inject an application-owned instance when you manage the tracing pipeline explicitly:

Client inttegro = new Client(
    System.getenv("INTTEGRO_API_KEY"),
    "https://api.inttegro.com",
    httpClient,
    openTelemetry
);

Inttegro emits vendor-neutral OpenTelemetry spans through the provider configured by your application. The SDK does not choose an exporter or observability vendor, and it does not send telemetry by itself.

Each public SDK call creates one CLIENT span named after the logical operation, such as inttegro.orders.create. HTTP attempts, retries, response receipt, decoding, and failures appear as events on that span. W3C trace context is propagated on outbound requests.

Span attributes and data-safety contract

The stable attributes are:

  • inttegro.operation.name, SDK language and SDK version
  • HTTP method and response status when available
  • destination host and the static API route template
  • the safe request identifier returned by the API
  • a low-cardinality failure category such as a timeout

SDK telemetry never records API keys, authorization headers, request or response bodies, customer or payment data, resource identifiers, dynamic URLs, query strings, exception messages, or stack traces.

To turn off Inttegro instrumentation for a client, use the five-argument Client constructor with telemetryEnabled set to false.

Report SDK failures​

Pass an application-owned callback to receive one immutable, typed report after an SDK operation finally fails:

import com.inttegro.Client;
import com.inttegro.diagnostics.ErrorReport;

public class Example {
    public static void main(String[] args) {
        Client inttegro = new Client(
            System.getenv("INTTEGRO_API_KEY"),
            (ErrorReport report) -> enqueueError(report)
        );
    }

    private static void enqueueError(ErrorReport report) {
        // Forward the report to your collector or queue.
    }
}

The default policy reports transport, timeout, decoding, SDK, unknown, and server-side failures. Expected API failures such as normal 4xx responses stay with the caller. Use ErrorReportingPolicy.ALL when the collector should receive those failures too. Cancellation is never reported.

Report fields and data-safety contract

A report contains:

  • the logical operation, static route, server host, status, duration, and safe request identifier when available
  • safe API error codes and a stable, low-cardinality fingerprint
  • SDK identity, exception type, and active trace identifiers

Reports never contain API keys, authorization headers, request or response bodies, customer or payment data, resource identifiers, dynamic URLs, query strings, exception messages, or stack traces.

Reporting is completely opt-in. Unless ErrorReporter is configured, the SDK does no reporting-specific timing or metadata preparation, creates no event ID or report object, and serializes nothing. Report construction and collector failures are isolated, so the caller still receives the original SDK failure.

Continue