Skip to content
Paylera

Java SDK — Getting started

The Paylera Java SDK ships as two Maven artefacts:

CoordinateWhen to use
dev.paylera:paylera-sdkA typed HTTP client for the Paylera API. Use it from any Java app — Spring, Quarkus, plain main(), AWS Lambda.
dev.paylera:paylera-spring-boot-starterSpring Boot 3 auto-configuration on top of the typed client: relay controller at /api/paylera/**, webhook receiver, CSRF + idempotency interceptors. Use it when your host app is Spring Boot.

Java 17+ is required. Both artefacts target the 2026-05-01 API version by default; pin a different version via PayleraClient.Builder#apiVersion(...) (typed client) or paylera.api-version: <date> (starter).

Install

Maven:

<!-- Typed client — Spring-or-not. -->
<dependency>
    <groupId>dev.paylera</groupId>
    <artifactId>paylera-sdk</artifactId>
    <version>0.0.0-SNAPSHOT</version>
</dependency>


<!-- Spring Boot autoconfig. Pulls in paylera-sdk transitively. -->
<dependency>
    <groupId>dev.paylera</groupId>
    <artifactId>paylera-spring-boot-starter</artifactId>
    <version>0.0.0-SNAPSHOT</version>
</dependency>

Gradle (Kotlin DSL):

implementation("dev.paylera:paylera-sdk:0.0.0-SNAPSHOT")
implementation("dev.paylera:paylera-spring-boot-starter:0.0.0-SNAPSHOT")

(Coordinates flip to a published Central artefact at v1; the 0.0.0-SNAPSHOT snapshot is the local-Maven coordinate used during SDK development. See Spring Boot starter for the local dev loop.)

First call — typed client

import dev.paylera.sdk.PayleraClient;
import dev.paylera.sdk.model.CheckRequest;


var client = PayleraClient.builder()
    .apiToken(System.getenv("PAYLERA_API_TOKEN"))
    .build();


var entitlement = client.check(new CheckRequest()
    .customerId(customerId)
    .featureCode("api_calls")
    .requiredUsage("1"));


if (Boolean.TRUE.equals(entitlement.getAllowed())) {
    // gate passed
}

PayleraClient is built once and reused across the lifetime of the JVM. It is thread-safe, holds the underlying OkHttpClient connection pool, and stamps every outbound request with Authorization: Bearer <token> and Paylera-Api-Version: 2026-05-01.

Base-URL routing

The client picks the base URL from the token prefix:

PrefixRoutes to
pl_live_*https://api.paylera.dev
pl_test_*https://api.test.paylera.dev
anythingexplicit baseUrl(...) required

Override:

var client = PayleraClient.builder()
    .apiToken(token)
    .baseUrl("https://staging.api.paylera.dev")
    .build();

Idempotency

POST/PUT/PATCH operations that require an Idempotency-Key on the wire get one auto-stamped (UUID v7, time-ordered). Override per call to share a key across your own retry budget:

client.track(
    new TrackRequest().customerId(id).featureCode("api_calls").value("1"),
    "stable-dedup-key",
    /* xRequestId */ null);

Errors

Every 4xx/5xx is translated into a typed subclass of PayleraException:

try {
    client.check(req);
} catch (PayleraAuthenticationException e) {
    // 401 — re-auth
} catch (PayleraRateLimitException e) {
    // 429 — back off (e.retryAfter() is set)
} catch (PayleraException e) {
    // base — everything else; e.getCode(), e.getDetail(), e.getRequestId()
}

See Direct client for the full subclass table.

First call — Spring Boot

application.yaml
paylera:
  api-token: ${PAYLERA_API_TOKEN}
  webhook-secret: ${PAYLERA_WEBHOOK_SECRET}
@Configuration
class PayleraConfig {
    @Bean
    PayleraIdentifier identifier() {
        return request -> PayleraCustomerIdentity.builder()
            .customerId(SecurityContext.user().getPayleraCustomerId())
            .email(SecurityContext.user().getEmail())
            .name(SecurityContext.user().getName())
            .build();
    }
}

That’s it. The starter auto-mounts the merchant-backend relay at /api/paylera/** and the webhook receiver at /webhooks/paylera. Browser-side, point @paylera/react’s <PayleraProvider basePath="/api/paylera"> at the same prefix.

See Spring Boot starter for the deep dive.

What the SDK does for you

  • Authentication — single bearer token, stamped on every call.
  • Retries — automatic 5xx + 429 retry with jittered exponential backoff, capped at 5 attempts. Retry-After honoured.
  • Idempotency — UUID v7 keys auto-stamped on writes; override per call.
  • Pagination — list responses carry a cursor; loop until null.
  • RFC 9457 problem-details — server errors parse into typed exceptions with getCode(), getDetail(), getRequestId().
  • OpenTelemetry — client-kind spans under Paylera.<Op>, no-op when no SDK is wired up. See OpenTelemetry.
  • Webhook verification — Paylera-Signature HMAC + replay-window check. See Webhooks.

What the SDK doesn’t do

  • Pick a DI container for you. PayleraClient is a plain final class — wire it however your app wires beans.
  • Persist tokens. You bring the secret manager.
  • Mutate global state. Multiple PayleraClient instances run side-by-side without conflict (different token, different base URL, whatever).

Where to next