Java SDK

The Java SDK requires Java 11+ and mirrors the client surface of the other Spare SDKs.

Coming soon, under review

This SDK is under review and not yet published, so the package is not installable yet. The steps below show the intended usage. Until release, integrate over the REST API.

Build a Configuration with your credentials, then create the client with SpareApiClient.fromConfiguration(). Token exchange, caching, and refresh are handled automatically, you never manage tokens directly.

import com.spare.Configuration;
import com.spare.SpareApiClient;

Configuration config = Configuration.builder()
    .appId(System.getenv("SPARE_APP_ID"))
    .apiKey(System.getenv("SPARE_API_KEY"))
    .tenant(System.getenv("SPARE_TENANT"))
    .build();

SpareApiClient client = SpareApiClient.fromConfiguration(config);

The X-Tenant header is injected on every request. Set SPARE_TENANT to the tenant for your market, see Coverage.

Common operations

import com.spare.resources.providers.requests.ProvidersListRequest;
import com.spare.resources.paymentrequests.requests.CreatePaymentRequestRequest;
import java.util.Map;

// List providers
var providers = client.providers().list(
    ProvidersListRequest.builder().countryCode("AE").build()
);
providers.getData().forEach(p -> System.out.println(p.getId() + " " + p.getName()));

// Create a payment request, requires an ES256 detached-JWS signature
Map<String, Object> body = new java.util.LinkedHashMap<>();
body.put("type", "SingleInstantPayment");
body.put("purpose", "ACM");
body.put("creditorType", "MERCHANT");
body.put("creditorReference", "INV-10042");
body.put("creditorAccount", Map.of(
    "identification", "AE070331234567890123456",
    "name", "Acme Corp",
    "schemeName", "IBAN"
));
body.put("instructions", Map.of(
    "amount", Map.of("amount", "250.00", "currency", "AED")
));

String xSignature = client.crypto().signPayload(
    System.getenv("SPARE_PRIVATE_KEY_PEM"), body);

var paymentRequest = client.paymentRequests().create(
    CreatePaymentRequestRequest.builder()
        .creditorReference("INV-10042")
        .purpose("ACM")
        .xSignature(xSignature)
        .build()
);

System.out.println("Payment request: " + paymentRequest.getData().getId());

Error handling

All non-2xx responses throw SpareApiApiException. Inspect statusCode() and body():

import com.spare.core.SpareApiApiException;

try {
    var consent = client.paymentConsents().get("consent-id");
} catch (SpareApiApiException e) {
    System.err.println(e.statusCode()); // HTTP status, e.g. 404
    System.err.println(e.body());       // raw response body
    throw e;
}

Resources

Quickstart
API Reference
Maven: com.spare:spare-api
Source repository: published when the SDK is released.

Installation

Configuration

Common operations

Error handling

Resources

On this page