Java SDK

The Java client (Java 11+) — typed requests and responses generated from the OpenAPI document, on the JDK's own HTTP client, plus a webhook signature verifier.

Getting it


Maven coordinates	`io.403fin:transmute-client`
Java package	`io.fin403.transmute` (generated client in `io.fin403.transmute.client`)
Java	11 or newer (tested on 17 and 21)
Runtime dependencies	Jackson, `jakarta.annotation-api`, `httpmime`; HTTP is `java.net.http.HttpClient`

<dependency>
  <groupId>io.403fin</groupId>
  <artifactId>transmute-client</artifactId>
  <version>X.Y.Z</version>
</dependency>

The SDK version tracks the API release: X.Y.Z is generated from API release vX.Y.Z.

Not on Maven Central yet. Until the first release is published, the SDK source and build are provided during onboarding — contact support.

Convert a message

import io.fin403.transmute.Transmute;
import io.fin403.transmute.client.ApiClient;
import io.fin403.transmute.client.api.EngineApi;
import io.fin403.transmute.client.model.ConvertRequest;
import io.fin403.transmute.client.model.ConvertResponse;
import io.fin403.transmute.client.model.Warning;

ApiClient client = Transmute.builder("https://api.transmute.403fin.io")
    .apiKey(System.getenv("TRANSMUTE_KEY"))
    .build();
EngineApi engine = new EngineApi(client);

String mt940 = String.join("\r
",
    "{1:F01AAAADEFFXXXX0000000000}{2:I940BBBBDEFFXXXXN}{4:",
    ":20:STMT0001",
    ":25:DE89370400440532013000",
    ":28C:00042/001",
    ":60F:C260601EUR1000,00",
    ":61:2606020602C250,00NTRFNONREF//BANKREF1",
    ":86:INVOICE 4711",
    ":62F:C260602EUR1250,00",
    "-}");

ConvertResponse resp = engine.convertMessage(
    EngineApi.APIConvertMessageRequest.newBuilder()
        .convertRequest(new ConvertRequest().to("camt.053").message(mt940)) // from omitted → auto-detect
        .build());

System.out.println(resp.getMeta().getDetectedType()); // "mt940"
String camt053 = resp.getResult().asText();
for (Warning w : resp.getWarnings()) {
  System.out.println(w.getCode() + " (" + w.getSeverity() + "): " + w.getDetail());
}

getResult() is a Jackson JsonNode: one string, or an array of strings when MT paging splits the output (meta.pages is then set). Transmute.builder(...).token(accessToken) authenticates with an OAuth access token instead of an API key. Errors throw ApiException: getCode() is the HTTP status and getResponseBody() the RFC 9457 problem document, whose type slug is in the error catalog.

API version, Standards Release and envelope

Option	Java	What it does
`X-Api-Version`	`Transmute.builder(...).apiVersion("2026-06-01")` for every request; `.xApiVersion(...)` on one request builder wins	Pins date-versioned behaviour — today, the default Standards Release. Unset: your API key's pin, else the current version. See Migrating from SR2025 to SR2026.
`srVersion`	`new ConvertOptions().srVersion(SRVersion.SR2026)` (also normalize, validate, batch)	Explicit Standards Release; always wins over the API version's default.
`envelope` (convert)	`new ConvertOptions().envelope(ConvertOptions.EnvelopeEnum.APPHDR)`; `FIN` for MT targets	`apphdr` adds a `head.001.001.02` Business Application Header before the MX `Document`; `fin` wraps MT output in FIN blocks 1 and 2.
`envelope` (normalize)	`new NormalizeOptions().envelope(NormalizeOptions.EnvelopeEnum.INCLUDE)`	Adds `result.envelope` (the source's FIN headers or Business Application Header).

Options you do not set are not sent: the API applies its own defaults, so an unpinned client follows the API version policy.

Verify a webhook delivery

import io.fin403.transmute.WebhookSignature;

try {
  WebhookSignature.verify(
      endpointSecret,                               // "whsec_..." — the full string
      request.getHeader("X-Transmute-Signature"),   // "t=...,v1=..."
      rawBody,                                      // raw bytes, read before parsing
      WebhookSignature.DEFAULT_TOLERANCE);          // 5 minutes
} catch (WebhookSignature.VerificationException e) {
  // respond 400
}

Constant-time comparison and the replay-window check are built in — see Webhooks for the delivery contract.

Notes

Generated with openapi-generator (java, native library) from the same OpenAPI document that serves api.transmute.403fin.io/docs, with the dashboard-internal portal routes removed; a CI gate keeps them in lockstep.
Amount fields are strings in all response types — parse with BigDecimal, never double.

"SWIFT" is a trademark of S.W.I.F.T. SCRL. transmute converts SWIFT MT messages; it is not affiliated with, endorsed by, or certified by SWIFT.

Was this page helpful?