SumUp Java SDK

IMPORTANT: This SDK is under heavy development and subject to breaking changes.

The Java SDK for the SumUp API generated from the canonical OpenAPI specification. Requires Java 17 or newer.

Installation

Gradle (Kotlin DSL)

Add the dependency in your build.gradle.kts file:

dependencies {
    implementation("com.sumup:sumup-sdk:0.1.3")
}

Gradle (Groovy)

Add the dependency in your build.gradle file:

dependencies {
    implementation 'com.sumup:sumup-sdk:0.1.3'
}

Maven

Add the dependency in your pom.xml file:

<dependency>
  <groupId>com.sumup</groupId>
  <artifactId>sumup-sdk</artifactId>
  <version>0.1.3</version>
</dependency>

Getting Started

Authenticate with a personal access token before making calls:

export SUMUP_API_KEY="my-token"

Create clients using the default constructor (reads SUMUP_API_KEY):

SumUpClient client = new SumUpClient();
SumUpAsyncClient asyncClient = new SumUpAsyncClient();

Or pass the API key explicitly:

SumUpClient client = new SumUpClient("api-key");

If you need more configuration, use the builder (for example, to override the base URL):

SumUpClient client =
    SumUpClient.builder()
        .baseUri("https://api.sumup.com")
        .build();

Usage

Creating an Online Checkout

Synchronous example:

import com.sumup.sdk.SumUpClient;
import com.sumup.sdk.models.CheckoutCreateRequest;
import com.sumup.sdk.models.Currency;
import java.util.UUID;

SumUpClient client =
    SumUpClient.builder()
        .build();

String merchantCode = client.merchant().getMerchantProfile().merchantCode();
String checkoutReference = "checkout-" + UUID.randomUUID();

CheckoutCreateRequest request =
    CheckoutCreateRequest.builder()
        .amount(10.00f)
        .currency(Currency.EUR)
        .checkoutReference(checkoutReference)
        .merchantCode(merchantCode)
        .description("Test payment")
        .redirectUrl("https://example.com/success")
        .returnUrl("https://example.com/webhook")
        .build();

var checkout = client.checkouts().create(request);
System.out.printf("Checkout %s created with id %s%n", checkout.checkoutReference(), checkout.id());

Asynchronous example:

import com.sumup.sdk.SumUpAsyncClient;
import com.sumup.sdk.models.CheckoutCreateRequest;
import com.sumup.sdk.models.Currency;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;

SumUpAsyncClient client =
    SumUpAsyncClient.builder()
        .build();

CompletableFuture<Void> checkoutFuture =
    client
        .merchant()
        .getMerchantProfile()
        .thenApply(profile -> profile.merchantCode())
        .thenCompose(
            merchantCode -> {
              String checkoutReference = "checkout-" + UUID.randomUUID();
              CheckoutCreateRequest request =
                  CheckoutCreateRequest.builder()
                      .amount(10.00f)
                      .currency(Currency.EUR)
                      .checkoutReference(checkoutReference)
                      .merchantCode(merchantCode)
                      .description("Test payment")
                      .redirectUrl("https://example.com/success")
                      .returnUrl("https://example.com/webhook")
                      .build();

              return client.checkouts().create(request);
            })
        .thenAccept(
            checkout ->
                System.out.printf(
                    "Checkout %s created (%s)%n",
                    checkout.checkoutReference(), checkout.id()));

checkoutFuture.join();

Creating a Card Reader Checkout

Synchronous example:

import com.sumup.sdk.SumUpClient;
import com.sumup.sdk.models.CreateReaderCheckoutRequest;
import com.sumup.sdk.models.Money;
import java.util.Optional;
import java.util.UUID;

String merchantCode = System.getenv("SUMUP_MERCHANT_CODE");

SumUpClient client =
    SumUpClient.builder()
        .build();

String readerId =
    Optional.ofNullable(System.getenv("SUMUP_READER_ID"))
        .orElseGet(
            () ->
                client.readers().list(merchantCode).items().stream()
                    .findFirst()
                    .map(reader -> reader.id())
                    .orElseThrow(() -> new IllegalStateException("No paired readers found.")));

CreateReaderCheckoutRequest request =
    CreateReaderCheckoutRequest.builder()
        .description("sumup-java reader checkout " + UUID.randomUUID())
        .totalAmount(
            Money.builder()
                .currency("EUR")
                .minorUnit(2L)
                .value(1000L) // €10.00
                .build())
        .returnUrl("https://example.com/webhook")
        .build();

client.readers().createCheckout(merchantCode, readerId, request);
System.out.println("Reader checkout created.");

Asynchronous example:

import com.sumup.sdk.SumUpAsyncClient;
import com.sumup.sdk.models.CreateReaderCheckoutRequest;
import com.sumup.sdk.models.Money;
import java.util.Optional;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;

String merchantCode = System.getenv("SUMUP_MERCHANT_CODE");

SumUpAsyncClient client =
    SumUpAsyncClient.builder()
        .build();

CompletableFuture<String> readerIdFuture =
    Optional.ofNullable(System.getenv("SUMUP_READER_ID"))
        .map(CompletableFuture::completedFuture)
        .orElseGet(
            () ->
                client
                    .readers()
                    .list(merchantCode)
                    .thenApply(
                        response ->
                            response.items().stream()
                                .findFirst()
                                .map(reader -> reader.id())
                                .orElseThrow(
                                    () ->
                                        new IllegalStateException("No paired readers found."))));

readerIdFuture
    .thenCompose(
        readerId -> {
          CreateReaderCheckoutRequest request =
              CreateReaderCheckoutRequest.builder()
                  .description("sumup-java reader checkout " + UUID.randomUUID())
                  .totalAmount(
                      Money.builder()
                          .currency("EUR")
                          .minorUnit(2L)
                          .value(1000L)
                          .build())
                  .returnUrl("https://example.com/webhook")
                  .build();

          return client.readers().createCheckout(merchantCode, readerId, request);
        })
    .thenAccept(
        response ->
            System.out.printf(
                "Reader checkout created: %s%n",
                Optional.ofNullable(response.data())
                    .map(data -> data.clientTransactionId())
                    .orElse("<unknown>")))
    .join();

Handling errors

Catch ApiStatusException to inspect an unsuccessful API response:

import com.sumup.sdk.core.ApiStatusException;

try {
    client.checkouts().get("your-checkout-id");
} catch (ApiStatusException error) {
    error.getProblem().ifPresent(problem ->
        System.out.println(problem.type() + ": " + problem.detail()));
}

getStatusCode(), getResponseBody(), and getResponseHeaders() provide the HTTP status, original response text, and headers. Connection failures raise ApiConnectionException; timeouts raise ApiTimeoutException. Both keep the original cause.

Handling events

var events = client.eventsHandler(secret, event ->
    System.out.printf("Unhandled event %s: %s%n", event.id(), event.type()));

events.onMemberUpdated(event -> {
    var member = event.fetchObject();
    System.out.printf("Member updated: %s%n", member.id());
});

events.handle(rawBody, signatureHeader);

Pass the original request bytes and the X-SumUp-Webhook-Signature header. The SDK verifies the signature and its fixed five-minute delivery window before processing. Register callbacks before serving requests and acknowledge delivery only after processing succeeds. Deliveries may repeat; use event IDs to deduplicate processing.

SumUpAsyncClient.eventsHandler accepts callbacks returning a CompletionStage<Void>. Call handleAsync and wait for its future to complete before acknowledging delivery. Use event.fetchObjectAsync() for asynchronous resource fetches.

Notifications wrap the generated Event model, available through event.payload(). Compare event.type() with constants such as EventType.MEMBERS_UPDATED; event.object() returns the generated EventObject reference. Unknown event and resource type names remain available through getValue().

For manual dispatch, use client.parseEventNotification(rawBody, signatureHeader, secret) and match the notification type. Unknown event types remain available as EventNotification. Resource fetches require an HTTP client with redirects disabled (the default). fetchObject retrieves the resource's current state; deleted resources may return an API error.

See the standalone HTTP-server example for a complete receiver.

Examples

examples/events – receives signed events using the JDK HTTP server.
examples/basic – lists recent checkouts to verify that your API token works.
examples/card-reader-checkout – lists paired readers and creates a €10 checkout on the first available device.

To run the card reader example locally:

export SUMUP_API_KEY="your_api_key"
export SUMUP_MERCHANT_CODE="your_merchant_code"
# Optional: pick a concrete reader instead of taking the first
# export SUMUP_READER_ID="your_reader_id"
./gradlew :examples:card-reader-checkout:run

For development instructions, see Contributing.

GeezerVison

Latest commit

History

Folders and files

Repository files navigation

SumUp Java SDK

Installation

Gradle (Kotlin DSL)

Gradle (Groovy)

Maven

Getting Started

Usage

Creating an Online Checkout

Creating a Card Reader Checkout

Handling errors

Handling events

Examples

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages