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.
Add the dependency in your build.gradle.kts file:
dependencies{implementation("com.sumup:sumup-sdk:0.0.6") }Add the dependency in your build.gradle file:
dependencies{implementation 'com.sumup:sumup-sdk:0.0.6' }Add the dependency in your pom.xml file:
<dependency> <groupId>com.sumup</groupId> <artifactId>sumup-sdk</artifactId> <version>0.0.6</version> </dependency>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):
SumUpClientclient = newSumUpClient(); SumUpAsyncClientasyncClient = newSumUpAsyncClient();Or pass the API key explicitly:
SumUpClientclient = newSumUpClient("api-key");If you need more configuration, use the builder (for example, to override the base URL):
SumUpClientclient = SumUpClient.builder() .baseUri("https://api.sumup.com") .build();Synchronous example:
importcom.sumup.sdk.SumUpClient; importcom.sumup.sdk.models.CheckoutCreateRequest; importcom.sumup.sdk.models.Currency; importjava.util.UUID; SumUpClientclient = SumUpClient.builder() .build(); StringmerchantCode = client.merchant().getMerchantProfile().merchantCode(); StringcheckoutReference = "checkout-" + UUID.randomUUID(); CheckoutCreateRequestrequest = 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(); varcheckout = client.checkouts().createCheckout(request); System.out.printf("Checkout %s created with id %s%n", checkout.checkoutReference(), checkout.id());Asynchronous example:
importcom.sumup.sdk.SumUpAsyncClient; importcom.sumup.sdk.models.CheckoutCreateRequest; importcom.sumup.sdk.models.Currency; importjava.util.UUID; importjava.util.concurrent.CompletableFuture; SumUpAsyncClientclient = SumUpAsyncClient.builder() .build(); CompletableFuture<Void> checkoutFuture = client .merchant() .getMerchantProfile() .thenApply(profile -> profile.merchantCode()) .thenCompose( merchantCode ->{StringcheckoutReference = "checkout-" + UUID.randomUUID(); CheckoutCreateRequestrequest = 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(); returnclient.checkouts().createCheckout(request)}) .thenAccept( checkout -> System.out.printf( "Checkout %s created (%s)%n", checkout.checkoutReference(), checkout.id())); checkoutFuture.join();Synchronous example:
importcom.sumup.sdk.SumUpClient; importcom.sumup.sdk.models.CreateReaderCheckoutRequest; importcom.sumup.sdk.models.Money; importjava.util.Optional; importjava.util.UUID; StringmerchantCode = System.getenv("SUMUP_MERCHANT_CODE"); SumUpClientclient = SumUpClient.builder() .build(); StringreaderId = Optional.ofNullable(System.getenv("SUMUP_READER_ID")) .orElseGet( () -> client.readers().listReaders(merchantCode).items().stream() .findFirst() .map(reader -> reader.id().value()) .orElseThrow(() -> newIllegalStateException("No paired readers found."))); CreateReaderCheckoutRequestrequest = 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().createReaderCheckout(merchantCode, readerId, request); System.out.println("Reader checkout created.");Asynchronous example:
importcom.sumup.sdk.SumUpAsyncClient; importcom.sumup.sdk.models.CreateReaderCheckoutRequest; importcom.sumup.sdk.models.Money; importjava.util.Optional; importjava.util.UUID; importjava.util.concurrent.CompletableFuture; StringmerchantCode = System.getenv("SUMUP_MERCHANT_CODE"); SumUpAsyncClientclient = SumUpAsyncClient.builder() .build(); CompletableFuture<String> readerIdFuture = Optional.ofNullable(System.getenv("SUMUP_READER_ID")) .map(CompletableFuture::completedFuture) .orElseGet( () -> client .readers() .listReaders(merchantCode) .thenApply( response -> response.items().stream() .findFirst() .map(reader -> reader.id().value()) .orElseThrow( () -> newIllegalStateException("No paired readers found.")))); readerIdFuture .thenCompose( readerId ->{CreateReaderCheckoutRequestrequest = 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(); returnclient.readers().createReaderCheckout(merchantCode, readerId, request)}) .thenAccept( response -> System.out.printf( "Reader checkout created: %s%n", Optional.ofNullable(response.data()) .map(data -> data.clientTransactionId()) .orElse("<unknown>"))) .join();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:runBuild the aggregated API reference locally with just javadoc (or ./gradlew aggregateJavadoc). The HTML output is placed under build/docs/javadoc/index.html.