Skip to main content

​
Overview

The SnapPay Java SDK provides a comprehensive, enterprise-grade interface for integrating payment processing, subscription management, and real-time event streaming into your Java applications. Built with modern Java patterns including CompletableFuture for asynchronous operations, reactive streams for event handling, and comprehensive type safety, it offers seamless integration with SnapPay’s complete platform. Requirements: Java 11+ / Maven or Gradle

​
Key Features

  • Modern async design with CompletableFuture and reactive patterns for optimal performance
  • Enterprise-grade reliability with connection pooling and automatic retry mechanisms
  • Real-time event streaming via Server-Sent Events (SSE) with reactive programming support
  • Full type safety with immutable POJOs and builder patterns
  • Thread-safe client for concurrent usage across your application
  • Comprehensive error handling with typed exceptions and detailed error contexts
  • Framework integrations for Spring Boot, Quarkus, and Micronaut
  • Environment-based configuration with flexible setup options

​
Installation

​
Maven

<dependency>
    <groupId>dev.snappay</groupId>
    <artifactId>snappay-sdk</artifactId>
    <version>0.0.1-beta</version>
</dependency>

​
Gradle

dependencies {
    implementation 'dev.snappay:snappay-sdk:0.0.1-beta'
}

​
Gradle (Kotlin DSL)

dependencies {
    implementation("dev.snappay:snappay-sdk:0.0.1-beta")
}

​
Configuration & Initialization

The SDK client is configured via a primary constructor that accepts a configuration object. All operations return CompletableFuture for asynchronous execution and proper resource management.

​
API Key Authentication

Authentication is handled via an API key that must start with pk_test_ (for testing) or pk_live_ (for production). Configure your API key in one of these ways:

​
SnapPay Client

Config config = new Config.Builder()
    .apiKey("pk_test_xxxxxxxxxx") // Required
    .build();

SnapPayClient client = new SnapPayClient(config);

​
Customer Management

​
getCustomer

Retrieves or creates a customer record. 
var customer = client.getCustomers().get(
    "user_124",
    "[email protected]",
    "John Dane 4"
);

public abstract fun get(
    id: String,
    email: String? = COMPILED_CODE,
    name: String? = COMPILED_CODE
): Customer
Parameters:
  • id (String): Customer identifier
  • email (String, optional): Customer email address
  • name (String, optional): Customer full name
Returns: 
public interface Customer {
    String getId();
    String getEmail();
    String getName();
    String getStatus();
}

​
Checkout Sessions

​
createCheckoutSession

Creates a payment checkout session URL for customer purchases. 
 var checkout = client.getCheckout().createSession(
                customer.getId(),
                "sand-pd-local-connect-3",
                null,
                "https://example.com/success",
                "https://example.com/cancel",
                "stripe"
        );

public abstract fun createSession(
    customerId: String,
    productId: String,
    priceId: String? = COMPILED_CODE,
    successUrl: String,
    cancelUrl: String? = COMPILED_CODE,
    provider: String = COMPILED_CODE
): CheckoutSession
Parameters:
  • customerId (String): SnapPay customer ID
  • productId (String): Product ID from your SnapPay dashboard
  • priceId (String): Price ID from your SnapPay dashboard
  • successUrl (String): URL to redirect after successful payment
  • cancelUrl (String, optional): URL to redirect on cancellation
  • provider (Provider): Payment provider (defaults to STRIPE)
Returns: 
public interface CheckoutSession {
    String getUrl();
    String getSessionId();
    String getExpiresAt();
}

​
Access Control

​
checkAccess

Checks if a customer has access to a specific feature based on their subscription and usage limits. 
var access = client.getAccess().check(
    "user_124",
    "sand-ft-messages"
);

public abstract fun check(
    customerId: String,
    featureId: String
): AccessResult
Parameters:
  • customerId (String): SnapPay customer ID
  • featureId (String): Feature identifier
Returns: 
public interface AccessResult {
    boolean getHasAccess();
    String getFeatureId();
    Integer getUsage();
    Integer getAllowance();
    Long getNextResetAt();
}

​
Usage Tracking

​
trackUsage

Reports usage for a metered feature. This action is idempotent to prevent duplicate tracking. 
var tracked = client.getUsage().track(
    customer.getId(),
    "sand-ft-messages",
    1
);

public abstract fun track(
    customerId: String,
    featureId: String,
    usage: Int,
    idempotencyKey: String?
): TrackUsage
Parameters:
  • customerId (String): SnapPay customer ID
  • featureId (String): Feature identifier for usage tracking
  • usage (Double): Usage amount to track
  • idempotencyKey (String, optional): Prevents duplicate tracking
Returns: 
public interface TrackUsage {
    String getCustomerId();
    String getFeatureId();
    int getAdded();
    int getUsed();
    String getTimestamp();
    String getIdempotencyKey();
}

​
getUsage

Retrieves current usage details for a customer’s feature. 
var usages = client.getUsage().get(customer.getId(), "sand-ft-messages");

public abstract fun get(
    customerId: String,
    featureId: String
): List<GetUsage>
Parameters:
  • customerId (String): SnapPay customer ID
  • featureId (String): Feature identifier
Returns: 
public interface GetUsage {
    int getTotalUsage();
    String getProductId();
    String getFeatureId();
    Integer getRemaining();
    Integer getLimit();
    Long getNextResetAt();
}

​
Real-time Event Handling

Say goodbye to webhook hell! SnapPay eliminates the complexity of managing payment webhooks by processing all provider webhooks (Stripe, PayPal, etc.) internally and delivering clean, structured events directly to your application via Server-Sent Events (SSE) using reactive patterns.

​
🚫 What You DON’T Need:

  • No webhook endpoints to create and maintain
  • No webhook signature verification
  • No webhook retry logic or failure handling
  • No webhook security concerns
  • No debugging webhook delivery issues

​
✅ What You GET:

  • Real-time events delivered instantly via reactive streams
  • Guaranteed delivery with automatic reconnection
  • Clean, structured data - no raw webhook payloads
  • Reactive programming perfect for Java’s async ecosystem
  • Type-safe event objects with comprehensive error handling

​
Event Structure

public interface SseEvent {
    String getId();
    SseEventType getType();
    Map<?, ?> getData();
    String getCreatedAt();
}

​
Supported Events

See the list of supported events: Server-sent Event Types

​
Reactive Event Streaming

Simply subscribe to events as they arrive - SnapPay handles all the webhook complexity behind the scenes: 
Flow.Publisher<SseEvent> publisher = client.getSse().subscribe();

publisher.subscribe(new Flow.Subscriber<>() {
    private Flow.Subscription subscription;

    @Override
    public void onSubscribe(Flow.Subscription subscription) {
        this.subscription = subscription;
        subscription.request(1);
    }

    @Override
    public void onNext(SseEvent event) {
        System.out.println("Java => Event: " + event.getType() + " | " + event);

        subscription.request(1);
    }

    @Override
    public void onError(Throwable throwable) {
        System.err.println("Java => Error: " + throwable.getMessage());
    }

    @Override
    public void onComplete() {
        System.out.println("Java => Stream completed");
    }
});
Key Benefits Demonstrated:
  • ✅ Zero webhook infrastructure - no endpoints, no servers, no security concerns
  • ✅ Instant event processing - no webhook delivery delays or failures
  • ✅ Reactive programming - perfect for Java’s async ecosystem
  • ✅ Type-safe event handling - compile-time safety with comprehensive error handling